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
}
'

{
  "success": true,
  "message": "Added 3 of 3 records",
  "results": {
    "total": 3,
    "valid": 3,
    "invalid": 0,
    "successful": 3,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

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
}
'

{
  "success": true,
  "message": "Added 3 of 3 records",
  "results": {
    "total": 3,
    "valid": 3,
    "invalid": 0,
    "successful": 3,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

Headers

Authorization

string

required

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

Body Parameters

campaignId

string

required

Target campaign ID. The campaign must already exist.

records

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

loan_id

string

required

Unique identifier for the loan record.

first_name

string

required

Customer’s first name.

last_name

string

required

Customer’s last name.

phone_number

string

required

Customer’s primary contact number.

loan_amount

number

required

Total principal amount of the loan.

emi_amount

number

required

EMI amount due for the current billing cycle.

loan_period

number

required

Total loan tenure in monthly installments.

current_emi

number

required

Current installment number in the repayment schedule (e.g., 5 of 12).

emi_due_date

string

required

Due date for the current EMI. Format: YYYY-MM-DD.

payment_status

string

required

Current status of the customer’s EMI payment.

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.

language

string

Preferred language for the AI agent (e.g., english, hindi, tamil).

Use this structure for new sales or lead acquisition.

Show item properties

lead_id

string

Unique identifier for the lead. Auto-generated (UUID) if not provided.

first_name

string

required

Customer’s first name.

last_name

string

required

Customer’s last name.

phone_number

string

required

Customer’s primary contact number.

lead_date

string

required

Date the lead was captured. Format: YYYY-MM-DD.

language

string

Preferred language for the AI agent (e.g., english, hindi, tamil).

initiateCall

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.

callConfig

object

Required when initiateCall is true.

Show properties

agentId

string

required

AI agent ID to handle the calls.

dispositionId

string

required

Disposition ID for call categorization.

useWorkflow

boolean

default:false

If true, triggers workflow execution asynchronously for all successfully added customers. Cannot be true if initiateCall is true.

Response

success

boolean

true if all records were added successfully, false if any failed.

message

string

Summary of the operation result.

results

object

Detailed breakdown of the operation.

Show properties

total

integer

Total records in the request.

valid

integer

Records that passed validation.

invalid

integer

Records that failed validation.

successful

integer

Records successfully added.

failed

integer

Records that failed to add.

batchesProcessed

integer

Number of batches processed.

errors

array

Array of error objects for failed records.

Show error object

string

The record ID that failed.

error

string

Error type.

reason

string

Human-readable error reason.

invalidRecords

array

Array of records that failed validation. Only present when there are invalid records.

Show invalid record object

index

integer

Position of the record in the input array.

string

The record ID, or null if missing.

errors

array

List of validation error messages.

callResults

object

Call initiation results. Only present when initiateCall was true.

Show properties

totalRequested

integer

Number of customers for whom calls were requested.

initiated

integer

Calls successfully initiated.

failed

integer

Calls that failed to initiate.

errors

array

Array of call initiation errors.

workflowTriggered

boolean

Whether workflow execution was triggered for successfully added customers. Only present when useWorkflow was true.

Response Status Codes:

201 — All records added successfully
207 — 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": []
  }
}

Add Customer Initiate Call(s)

​Headers

​Body Parameters

​Response

Headers

Body Parameters

Response