Batch Create Contacts
POST
/contacts/batch
Authentication
contacts:writeRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
contacts | array | Yes | Array of contact objects to create |
options | object | No | Batch operation options |
options.continue_on_error | boolean | No | Continue processing remaining contacts if one fails (default: true) |
options.skip_duplicates | boolean | No | Skip contacts with duplicate phone numbers instead of failing (default: false) |
Contact Object Fields
contacts array follows the same validation as the single create endpoint:| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
firstname | string | Yes | max:255 | First name |
lastname | string | Yes | max:255 | Last name |
phone | string | Yes | max:20 | Phone number with country code |
type | string | Yes | lead, customer, guest | Contact type |
source_id | integer | Yes | — | Source ID |
status_id | integer | Yes | — | Status ID |
email | string | No | email, max:191 | Email address |
company | string | No | max:255 | Company name |
description | string | No | — | Additional notes |
city | string | No | max:255 | City |
state | string | No | max:255 | State/province |
zip | string | No | max:20 | ZIP/postal code |
address | string | No | max:500 | Street address |
country_id | integer | No | — | Country ID |
assigned_id | integer | No | — | Assigned user ID |
Duplicate Detection
options.skip_duplicates is true, the phone field is used as the unique identifier. Contacts with an existing phone number in the tenant will be skipped (not failed).Response
Response Data Structure
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the overall operation succeeded |
summary.total | integer | Total contacts submitted |
summary.created | integer | Number successfully created |
summary.skipped | integer | Number skipped (duplicates) |
summary.failed | integer | Number that failed validation |
created | array | Array of created contact objects |
skipped | array | Array of skipped entries with index, reason, data |
errors | array | Array of failed entries with index, data, errors |
Error Responses
| Status | Code | Description |
|---|---|---|
| 422 | VALIDATION_ERROR | Batch operation failed (when continue_on_error is false and a contact fails) |
| 500 | INTERNAL_ERROR | Batch operation failed (database error, transaction rolled back) |
Note: Feature usage count ( contacts) is synced after batch completion viasyncModelCount.
Request
Header Params
Body Params application/json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/contacts/batch' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"contacts": [
{
"firstname": "Test",
"lastname": "Three",
"type": "lead",
"email": "testthree@gmail.com",
"phone": "+919587422390",
"source_id": 115,
"status_id": 287,
"description": "Test one contact",
"country_id": 101,
"group_id": [
12
],
"zip": "360001",
"city": "Rajkot"
},
{
"firstname": "Test",
"lastname": "Four",
"type": "customer",
"email": "testfour@gmail.com",
"phone": "+919587422355",
"source_id": 115,
"status_id": 287,
"description": "Test one contact",
"country_id": 101,
"addedfrom": 1
}
],
"options": {
"continue_on_error": true,
"skip_duplicates": false
}
}'Response Response Example
{}Modified at 2026-02-25 01:06:20