Initiate Call(s)

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "dispositionId": "<string>",
  "limit": 123,
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls"

payload = {
    "agentId": "<string>",
    "dispositionId": "<string>",
    "limit": 123,
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: '<string>',
    dispositionId: '<string>',
    limit: 123,
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agentId' => '<string>',
    'dispositionId' => '<string>',
    'limit' => 123,
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls"

	payload := strings.NewReader("{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Calls initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "Calls initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Call initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "agentId is required and must be a string"
  ]
}

{
  "success": false,
  "message": "No active numbers available for this organization"
}

{
  "success": false,
  "message": "Cannot initiate calls: Missing variables: emi_due_date, loan_amount",
  "totalMatched": 250,
  "customersSelected": 250
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "Agent not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "message": "Campaign ID invalid or mismatch for your organization."
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Initiate Call(s)

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "dispositionId": "<string>",
  "limit": 123,
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls"

payload = {
    "agentId": "<string>",
    "dispositionId": "<string>",
    "limit": 123,
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: '<string>',
    dispositionId: '<string>',
    limit: 123,
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agentId' => '<string>',
    'dispositionId' => '<string>',
    'limit' => 123,
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls"

	payload := strings.NewReader("{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agentId\": \"<string>\",\n  \"dispositionId\": \"<string>\",\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Calls initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "Calls initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Call initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "agentId is required and must be a string"
  ]
}

{
  "success": false,
  "message": "No active numbers available for this organization"
}

{
  "success": false,
  "message": "Cannot initiate calls: Missing variables: emi_due_date, loan_amount",
  "totalMatched": 250,
  "customersSelected": 250
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "Agent not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "message": "Campaign ID invalid or mismatch for your organization."
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Headers

string

required

Bearer token for authentication (e.g., Bearer <your_token>).

Path Parameters

string

required

The campaign ID containing the customers to call.

Body Parameters

string

required

AI agent ID to handle the calls.

string

required

Disposition ID for call categorization.

integer

Maximum number of customers to call. If omitted, all matching customers are called.

object

Optional filters to target specific customers. If omitted, all customers in the campaign are called. Multiple filters are combined with AND logic.

Show filter properties

string[]

Call only these specific customer IDs (loan_id or lead_id).

string[]

Exclude these customer IDs from calling.

string[]

Filter by payment status. Accepts a single value or an array.

Show options

bounced — Payment was attempted but failed.
pending — Payment is due but not yet initiated.
partial — Customer has made a partial payment.
paid — Payment has been completed.
received — Payment has been received and confirmed.

string[]

Filter by customer language preference. Accepts a single value or an array (e.g., "hindi" or ["hindi", "english"]).

object

Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings.

Example

      {
        "branch": "mumbai",
        "product_type": ["personal_loan", "home_loan"]
      }

Response

boolean

true if all calls were initiated successfully, false otherwise.

string

Summary of the operation result.

object

Detailed breakdown of the call initiation.

Show properties

integer

Total customers matching the query/filters in the campaign.

integer

Customers selected for calling (respects limit if provided).

integer

Calls successfully initiated.

integer

Calls that failed to initiate.

integer

Number of call batches processed (500 customers per batch).

array

Array of error objects for failed batches.

Show error object

integer

Batch number that failed.

string

Error type.

string

Human-readable error reason.

integer

Number of customers affected in the failed batch.

Response Status Codes:

200 — All calls initiated successfully
207 — Partial success (some calls initiated, some failed)
400 — Validation error, no active numbers, or missing agent variables
404 — Campaign, agent, or customers not found
500 — All calls failed or internal server error

{
  "success": true,
  "message": "Calls initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "Calls initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Call initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "agentId is required and must be a string"
  ]
}

{
  "success": false,
  "message": "No active numbers available for this organization"
}

{
  "success": false,
  "message": "Cannot initiate calls: Missing variables: emi_due_date, loan_amount",
  "totalMatched": 250,
  "customersSelected": 250
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "Agent not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "message": "Campaign ID invalid or mismatch for your organization."
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Usage Examples

Call all customers in a campaign:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789"
}

Call only bounced and pending customers:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "payment_status": ["bounced", "pending"]
  }
}

Call customers with EMI due this month, limited to 100:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "limit": 100,
  "filters": {
    "emi_due_date": {
      "from": "2025-08-01",
      "to": "2025-08-31"
    },
    "payment_status": "pending"
  }
}

Call specific customers by ID:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "ids": ["LOAN-2025-00123", "LOAN-2025-00456", "LOAN-2025-00789"]
  }
}

Call with custom field filters:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "payment_status": ["bounced", "pending"],
    "emi_amount": {
      "min": 5000,
      "max": 20000
    },
    "language": "hindi",
    "custom": {
      "branch": "mumbai",
      "product_type": ["personal_loan", "home_loan"]
    }
  }
}

Call all customers except specific ones:

{
  "agentId": "agent_abc123",
  "dispositionId": "disp_xyz789",
  "filters": {
    "exclude_ids": ["LOAN-2025-00789", "LOAN-2025-00999"]
  }
}

​Headers

​Path Parameters

​Body Parameters

​Response

​Usage Examples

Headers

Path Parameters

Body Parameters

Response

Usage Examples