> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk Add Customers
> Add multiple customer records to an existing campaign in a single request with optional call initiation.
### Headers
Bearer token for authentication (e.g., `Bearer `).
### Body Parameters
Target campaign ID. The campaign must already exist.
Array of customer objects. Maximum **10,000** records per request. The required fields depend on your campaign's service type.
**Use this structure if you are managing existing loans.**
Unique identifier for the loan record.
Customer's first name.
Customer's last name.
Customer's primary contact number.
Total principal amount of the loan.
EMI amount due for the current billing cycle.
Total loan tenure in monthly installments.
Current installment number in the repayment schedule (e.g., 5 of 12).
Due date for the current EMI. Format: `YYYY-MM-DD`.
Current status of the customer's EMI payment.
* `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.
Preferred language for the AI agent (e.g., `english`, `hindi`, `tamil`).
**Use this structure for new sales or lead acquisition.**
Unique identifier for the lead. Auto-generated (UUID) if not provided.
Customer's first name.
Customer's last name.
Customer's primary contact number.
Date the lead was captured. Format: `YYYY-MM-DD`.
Preferred language for the AI agent (e.g., `english`, `hindi`, `tamil`).
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`.
Required when `initiateCall` is `true`.
AI agent ID to handle the calls.
Disposition ID for call categorization.
If `true`, triggers workflow execution asynchronously for all successfully added customers. Cannot be `true` if `initiateCall` is `true`.
### Response
`true` if all records were added successfully, `false` if any failed.
Summary of the operation result.
Detailed breakdown of the operation.
Total records in the request.
Records that passed validation.
Records that failed validation.
Records successfully added.
Records that failed to add.
Number of batches processed.
Array of error objects for failed records.
The record ID that failed.
Error type.
Human-readable error reason.
Array of records that failed validation. Only present when there are invalid records.
Position of the record in the input array.
The record ID, or `null` if missing.
List of validation error messages.
Call initiation results. Only present when `initiateCall` was `true`.
Number of customers for whom calls were requested.
Calls successfully initiated.
Calls that failed to initiate.
Array of call initiation errors.
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
```json 201 All Added Successfully theme={null}
{
"success": true,
"message": "Added 3 of 3 records",
"results": {
"total": 3,
"valid": 3,
"invalid": 0,
"successful": 3,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
```
```json 201 All Added with Calls theme={null}
{
"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": []
}
}
```
```json 201 All Added with Workflow theme={null}
{
"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
}
```
```json 207 Partial Success theme={null}
{
"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'"
]
}
]
}
}
```
```json 400 Validation Error theme={null}
{
"success": false,
"message": "Validation failed",
"errors": [
"campaignId is required and must be a string"
]
}
```
```json 400 No Valid Records theme={null}
{
"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'"
]
}
]
}
```
```json 404 Campaign Not Found theme={null}
{
"success": false,
"message": "Campaign not found"
}
```
```json 403 Forbidden theme={null}
{
"success": false,
"message": "Campaign ID invalid or mismatch for your organization."
}
```
```json 500 Server Error theme={null}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
```