Add Customer
curl --request POST \
--url https://api.agents.timepay.ai/api/v1/customers/add \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"campaignId": "<string>",
"data": {
"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"
payload = {
"campaignId": "<string>",
"data": {
"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>',
data: {
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', 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",
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>',
'data' => [
'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"
payload := strings.NewReader("{\n \"campaignId\": \"<string>\",\n \"data\": {\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 \"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")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"campaignId\": \"<string>\",\n \"data\": {\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 \"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")
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 \"data\": {\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 \"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": "Customer added to campaign successfully",
"data": {
"id": "LOAN-2025-00123",
"campaignId": "camp_abc123"
}
}
{
"success": true,
"message": "Customer added and call initiated successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": true
}
{
"success": true,
"message": "Customer added and workflow triggered successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"workflowTriggered": true
}
{
"success": true,
"message": "Customer added successfully but call could not be initiated: No active numbers available",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": false,
"callError": "No active numbers available for this organization"
}
{
"success": false,
"message": "Validation failed",
"errors": [
"Record 0: Missing required field 'phone_number'",
"Record 0: Missing required field 'emi_due_date'"
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Customer with loan_id 'LOAN-2025-00123' already exists in this campaign."
}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
Customers
Add Customer
Add a single customer record to an existing campaign with optional immediate call initiation.
Add Customer
curl --request POST \
--url https://api.agents.timepay.ai/api/v1/customers/add \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"campaignId": "<string>",
"data": {
"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"
payload = {
"campaignId": "<string>",
"data": {
"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>',
data: {
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', 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",
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>',
'data' => [
'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"
payload := strings.NewReader("{\n \"campaignId\": \"<string>\",\n \"data\": {\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 \"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")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"campaignId\": \"<string>\",\n \"data\": {\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 \"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")
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 \"data\": {\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 \"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": "Customer added to campaign successfully",
"data": {
"id": "LOAN-2025-00123",
"campaignId": "camp_abc123"
}
}
{
"success": true,
"message": "Customer added and call initiated successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": true
}
{
"success": true,
"message": "Customer added and workflow triggered successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"workflowTriggered": true
}
{
"success": true,
"message": "Customer added successfully but call could not be initiated: No active numbers available",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": false,
"callError": "No active numbers available for this organization"
}
{
"success": false,
"message": "Validation failed",
"errors": [
"Record 0: Missing required field 'phone_number'",
"Record 0: Missing required field 'emi_due_date'"
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Customer with loan_id 'LOAN-2025-00123' already exists in this campaign."
}
{
"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.
object
required
Customer data object. 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 a call to the customer immediately after adding. Requires callConfig. Cannot be true if useWorkflow is true.object
boolean
default:false
If
true, triggers workflow execution asynchronously. Cannot be true if initiateCall is true.Response
boolean
Indicates whether the request was successful.
string
A descriptive message about the result.
object
boolean
Whether the call was successfully initiated. Only present when
initiateCall was true.string
Reason the call could not be initiated. Only present when
callInitiated is false.boolean
Whether the workflow execution was triggered. Only present when
useWorkflow was true.{
"success": true,
"message": "Customer added to campaign successfully",
"data": {
"id": "LOAN-2025-00123",
"campaignId": "camp_abc123"
}
}
{
"success": true,
"message": "Customer added and call initiated successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": true
}
{
"success": true,
"message": "Customer added and workflow triggered successfully",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"workflowTriggered": true
}
{
"success": true,
"message": "Customer added successfully but call could not be initiated: No active numbers available",
"data": {
"id": "LOAN-2025-00456",
"campaignId": "camp_abc123"
},
"callInitiated": false,
"callError": "No active numbers available for this organization"
}
{
"success": false,
"message": "Validation failed",
"errors": [
"Record 0: Missing required field 'phone_number'",
"Record 0: Missing required field 'emi_due_date'"
]
}
{
"success": false,
"message": "Campaign not found"
}
{
"success": false,
"message": "Customer with loan_id 'LOAN-2025-00123' already exists in this campaign."
}
{
"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 - required customer data is missing or invalid |
401 | Unauthorized - missing or invalid authorization header |
403 | Forbidden - campaign does not belong to the organization |
404 | Campaign not found |
409 | A customer with the supplied loan ID already exists in the campaign |
500 | Internal server error |