Bulk Add Customers
curl --request POST \
--url https://api.agents.timepay.ai/api/v1/customers/add/bulk \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"campaignId": "<string>",
"records": [
{
"loan_id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"phone_number": "<string>",
"loan_amount": 123,
"emi_amount": 123,
"loan_period": 123,
"current_emi": 123,
"emi_due_date": "<string>",
"payment_status": "<string>",
"language": "<string>",
"lead_id": "<string>",
"lead_date": "<string>"
}
],
"initiateCall": true,
"callConfig": {
"agentId": "<string>",
"dispositionId": "<string>"
},
"useWorkflow": true
}
'import requests
url = "https://api.agents.timepay.ai/api/v1/customers/add/bulk"
payload = {
"campaignId": "<string>",
"records": [
{
"loan_id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"phone_number": "<string>",
"loan_amount": 123,
"emi_amount": 123,
"loan_period": 123,
"current_emi": 123,
"emi_due_date": "<string>",
"payment_status": "<string>",
"language": "<string>",
"lead_id": "<string>",
"lead_date": "<string>"
}
],
"initiateCall": True,
"callConfig": {
"agentId": "<string>",
"dispositionId": "<string>"
},
"useWorkflow": True
}
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({
campaignId: '<string>',
records: [
{
loan_id: '<string>',
first_name: '<string>',
last_name: '<string>',
phone_number: '<string>',
loan_amount: 123,
emi_amount: 123,
loan_period: 123,
current_emi: 123,
emi_due_date: '<string>',
payment_status: '<string>',
language: '<string>',
lead_id: '<string>',
lead_date: '<string>'
}
],
initiateCall: true,
callConfig: {agentId: '<string>', dispositionId: '<string>'},
useWorkflow: true
})
};
fetch('https://api.agents.timepay.ai/api/v1/customers/add/bulk', 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/customers/add/bulk",
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([
'campaignId' => '<string>',
'records' => [
[
'loan_id' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'phone_number' => '<string>',
'loan_amount' => 123,
'emi_amount' => 123,
'loan_period' => 123,
'current_emi' => 123,
'emi_due_date' => '<string>',
'payment_status' => '<string>',
'language' => '<string>',
'lead_id' => '<string>',
'lead_date' => '<string>'
]
],
'initiateCall' => true,
'callConfig' => [
'agentId' => '<string>',
'dispositionId' => '<string>'
],
'useWorkflow' => true
]),
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/customers/add/bulk"
payload := strings.NewReader("{\n \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\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/customers/add/bulk")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agents.timepay.ai/api/v1/customers/add/bulk")
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 \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Added 3 of 3 records",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Calls initiated for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"callResults": {
"totalRequested": 3,
"initiated": 3,
"failed": 0,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Workflow triggered for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"workflowTriggered": true
}
{
"success": false,
"message": "Added 2 of 3 records",
"results": {
"total": 3,
"valid": 2,
"invalid": 1,
"successful": 2,
"failed": 1,
"batchesProcessed": 1,
"errors": [],
"invalidRecords": [
{
"index": 2,
"id": null,
"errors": [
"Record 2: Missing required field 'phone_number'",
"Record 2: Missing required field 'loan_amount'"
]
}
]
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
"campaignId is required and must be a string"
]
}
{
"success": false,
"message": "No valid records to add",
"invalidRecords": [
{
"index": 0,
"id": null,
"errors": [
"Record 0: Missing required field 'first_name'",
"Record 0: Missing required field 'phone_number'"
]
}
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
Customers
Bulk Add Customers
Add multiple customer records to an existing campaign in a single request with optional call initiation.
Bulk Add Customers
curl --request POST \
--url https://api.agents.timepay.ai/api/v1/customers/add/bulk \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"campaignId": "<string>",
"records": [
{
"loan_id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"phone_number": "<string>",
"loan_amount": 123,
"emi_amount": 123,
"loan_period": 123,
"current_emi": 123,
"emi_due_date": "<string>",
"payment_status": "<string>",
"language": "<string>",
"lead_id": "<string>",
"lead_date": "<string>"
}
],
"initiateCall": true,
"callConfig": {
"agentId": "<string>",
"dispositionId": "<string>"
},
"useWorkflow": true
}
'import requests
url = "https://api.agents.timepay.ai/api/v1/customers/add/bulk"
payload = {
"campaignId": "<string>",
"records": [
{
"loan_id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"phone_number": "<string>",
"loan_amount": 123,
"emi_amount": 123,
"loan_period": 123,
"current_emi": 123,
"emi_due_date": "<string>",
"payment_status": "<string>",
"language": "<string>",
"lead_id": "<string>",
"lead_date": "<string>"
}
],
"initiateCall": True,
"callConfig": {
"agentId": "<string>",
"dispositionId": "<string>"
},
"useWorkflow": True
}
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({
campaignId: '<string>',
records: [
{
loan_id: '<string>',
first_name: '<string>',
last_name: '<string>',
phone_number: '<string>',
loan_amount: 123,
emi_amount: 123,
loan_period: 123,
current_emi: 123,
emi_due_date: '<string>',
payment_status: '<string>',
language: '<string>',
lead_id: '<string>',
lead_date: '<string>'
}
],
initiateCall: true,
callConfig: {agentId: '<string>', dispositionId: '<string>'},
useWorkflow: true
})
};
fetch('https://api.agents.timepay.ai/api/v1/customers/add/bulk', 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/customers/add/bulk",
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([
'campaignId' => '<string>',
'records' => [
[
'loan_id' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'phone_number' => '<string>',
'loan_amount' => 123,
'emi_amount' => 123,
'loan_period' => 123,
'current_emi' => 123,
'emi_due_date' => '<string>',
'payment_status' => '<string>',
'language' => '<string>',
'lead_id' => '<string>',
'lead_date' => '<string>'
]
],
'initiateCall' => true,
'callConfig' => [
'agentId' => '<string>',
'dispositionId' => '<string>'
],
'useWorkflow' => true
]),
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/customers/add/bulk"
payload := strings.NewReader("{\n \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\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/customers/add/bulk")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agents.timepay.ai/api/v1/customers/add/bulk")
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 \"campaignId\": \"<string>\",\n \"records\": [\n {\n \"loan_id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"loan_amount\": 123,\n \"emi_amount\": 123,\n \"loan_period\": 123,\n \"current_emi\": 123,\n \"emi_due_date\": \"<string>\",\n \"payment_status\": \"<string>\",\n \"language\": \"<string>\",\n \"lead_id\": \"<string>\",\n \"lead_date\": \"<string>\"\n }\n ],\n \"initiateCall\": true,\n \"callConfig\": {\n \"agentId\": \"<string>\",\n \"dispositionId\": \"<string>\"\n },\n \"useWorkflow\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Added 3 of 3 records",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Calls initiated for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"callResults": {
"totalRequested": 3,
"initiated": 3,
"failed": 0,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Workflow triggered for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"workflowTriggered": true
}
{
"success": false,
"message": "Added 2 of 3 records",
"results": {
"total": 3,
"valid": 2,
"invalid": 1,
"successful": 2,
"failed": 1,
"batchesProcessed": 1,
"errors": [],
"invalidRecords": [
{
"index": 2,
"id": null,
"errors": [
"Record 2: Missing required field 'phone_number'",
"Record 2: Missing required field 'loan_amount'"
]
}
]
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
"campaignId is required and must be a string"
]
}
{
"success": false,
"message": "No valid records to add",
"invalidRecords": [
{
"index": 0,
"id": null,
"errors": [
"Record 0: Missing required field 'first_name'",
"Record 0: Missing required field 'phone_number'"
]
}
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
Headers
401 Unauthorized
{
"success": false,
"error": "Unauthorized",
"message": "Missing or invalid authorization header"
}
string
required
Bearer token for authentication (e.g.,
Bearer <your_token>).string
Optional. Use this header only when the authenticated user belongs to multiple organizations. It identifies the organization to target for this action.
Body Parameters
string
required
Target campaign ID. The campaign must already exist.
array
required
Array of customer objects. Maximum 10,000 records per request. The required fields depend on your campaign’s service type.
- Debt Collection
- Lead Generation
Use this structure if you are managing existing loans.
Show item properties
Show item properties
string
required
Unique identifier for the loan record.
string
required
Customer’s first name.
string
required
Customer’s last name.
string
required
Customer’s primary contact number.
number
required
Total principal amount of the loan.
number
required
EMI amount due for the current billing cycle.
number
required
Total loan tenure in monthly installments.
number
required
Current installment number in the repayment schedule (e.g., 5 of 12).
string
required
Due date for the current EMI. Format:
YYYY-MM-DD.string
required
Current status of the customer’s EMI payment.
Show options
Show options
bounced— Payment was attempted but failed (e.g., insufficient funds).pending— Payment is due but not yet initiated.partial— Customer has made a partial payment.paid— Payment has been completed by the customer.received— Payment has been received and confirmed.
string
Preferred language for the AI agent (e.g.,
english, hindi, tamil).Use this structure for new sales or lead acquisition.
Show item properties
Show item properties
string
Unique identifier for the lead. Auto-generated (UUID) if not provided.
string
required
Customer’s first name.
string
required
Customer’s last name.
string
required
Customer’s primary contact number.
string
required
Date the lead was captured. Format:
YYYY-MM-DD.string
Preferred language for the AI agent (e.g.,
english, hindi, tamil).boolean
default:false
If
true, initiates calls for all successfully added customers. Requires callConfig. Calls are triggered in batches of 500 after all records are added. Cannot be true if useWorkflow is true.object
boolean
default:false
If
true, triggers workflow execution asynchronously for all successfully added customers. Cannot be true if initiateCall is true.Response
boolean
true if all records were added successfully, false if any failed.string
Summary of the operation result.
object
Detailed breakdown of the operation.
Show properties
Show properties
integer
Total records in the request.
integer
Records that passed validation.
integer
Records that failed validation.
integer
Records successfully added.
integer
Records that failed to add.
integer
Number of batches processed.
array
object
boolean
Whether workflow execution was triggered for successfully added customers. Only present when
useWorkflow was true.Response Status Codes:
201— All records added successfully207— Partial success (some added, some failed)400— All records failed or validation error
{
"success": true,
"message": "Added 3 of 3 records",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Calls initiated for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"callResults": {
"totalRequested": 3,
"initiated": 3,
"failed": 0,
"errors": []
}
}
{
"success": true,
"message": "Added 3 of 3 records | Workflow triggered for 3 customers",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
},
"workflowTriggered": true
}
{
"success": false,
"message": "Added 2 of 3 records",
"results": {
"total": 3,
"valid": 2,
"invalid": 1,
"successful": 2,
"failed": 1,
"batchesProcessed": 1,
"errors": [],
"invalidRecords": [
{
"index": 2,
"id": null,
"errors": [
"Record 2: Missing required field 'phone_number'",
"Record 2: Missing required field 'loan_amount'"
]
}
]
}
}
{
"success": false,
"message": "Validation failed",
"errors": [
"campaignId is required and must be a string"
]
}
{
"success": false,
"message": "No valid records to add",
"invalidRecords": [
{
"index": 0,
"id": null,
"errors": [
"Record 0: Missing required field 'first_name'",
"Record 0: Missing required field 'phone_number'"
]
}
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
Error Codes
| Status | Description |
|---|---|
400 | Validation error or no valid customer records supplied |
401 | Unauthorized - missing or invalid authorization header |
403 | Forbidden - campaign does not belong to the organization |
404 | Campaign not found |
500 | Internal server error |