Add Contacts
Campaign Contact API
Overview
This API endpoint allows you to add contacts to an existing campaign within the automation system. The endpoint supports both single contact and bulk contact addition operations.
Endpoint
POST https://www.tabbly.io/dashboard/agents/endpoints/add-campaign-contacts
Authentication
Authentication is performed via API key, which must be included in the request body.
Request Format
The endpoint accepts data in JSON format. There are two modes of operation:
1. Single Contact Addition
api_key
String
Your organization's unique API key
Yes
phone_number
String
Contact's phone number
Yes
campaign_id
Integer
ID of the campaign to add the contact to
Yes
participant_identity
String
Name or identifier of the contact
Yes
use_agent_id
Integer
ID of the agent to use for this contact
Yes
created_by
String
Identifier of who created this contact
Yes
custom_first_line
String
Custom first line for this specific contact
Yes
custom_instruction
String
Additional instructions for handling this contact
Yes
sip_call_id
String
SIP call identifier
Yes
created_time
String
Timestamp for contact creation (defaults to now)
No
called
Integer
Whether contact has been called (0 or 1, defaults to 0)
No
call_counter
Integer
Number of call attempts (defaults to 0)
No
custom_identifiers
String
Pass key value pairs, jSON payloads for mapping user back to your system via webhooks / call logs API.
YES
2. Bulk Contact Addition
For bulk operations, wrap your contacts in a contacts
array:
api_key
String
Your organization's unique API key
Yes
contacts
Array
Array of contact objects, each containing the fields above
Yes
Example Requests
Single Contact Addition
{
"api_key": "your_api_key_here",
"phone_number": "+15551234567",
"campaign_id": 456,
"participant_identity": "John Doe",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello John, this is regarding your recent inquiry.",
"custom_instruction": "Mention the new product line",
"sip_call_id": "call_987654321",
"custom_identifiers": "user_id=3324123123xewqw"
}
cURL Example (Single Contact)
curl -X POST https://www.tabbly.io/dashboard/agents/endpoints/add-campaign-contacts \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key_here",
"phone_number": "+15551234567",
"campaign_id": 456,
"participant_identity": "John Doe",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello John, this is regarding your recent inquiry.",
"custom_instruction": "Mention the new product line",
"sip_call_id": "call_987654321",
"custom_identifiers": "user_id=3324123123xewqw"
}'
Bulk Contact Addition
{
"api_key": "your_api_key_here",
"contacts": [
{
"phone_number": "+15551234567",
"campaign_id": 456,
"participant_identity": "John Doe",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello John, this is regarding your recent inquiry.",
"custom_instruction": "Mention the new product line",
"sip_call_id": "call_987654321",
"custom_identifiers": "user_id=3324123123xewqw"
},
{
"phone_number": "+15559876543",
"campaign_id": 456,
"participant_identity": "Jane Smith",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello Jane, this is regarding your recent inquiry.",
"custom_instruction": "Discuss premium options",
"sip_call_id": "call_123456789",
"custom_identifiers": "user_id=abcfg3324123134"
}
]
}
cURL Example (Bulk Contacts)
curl -X POST https://www.tabbly.io/dashboard/agents/endpoints/add-campaign-contacts \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key_here",
"contacts": [
{
"phone_number": "+15551234567",
"campaign_id": 456,
"participant_identity": "John Doe",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello John, this is regarding your recent inquiry.",
"custom_instruction": "Mention the new product line",
"sip_call_id": "call_987654321",
"custom_identifiers": "user_id=abcfg3324123134"
},
{
"phone_number": "+15559876543",
"campaign_id": 456,
"participant_identity": "Jane Smith",
"use_agent_id": 123,
"created_by": "API",
"custom_first_line": "Hello Jane, this is regarding your recent inquiry.",
"custom_instruction": "Discuss premium options",
"sip_call_id": "call_123456789",
"custom_identifiers": "user_id=gbfheu34xe"
}
]
}'
Response Format
Success Response (Single Contact)
{
"status": "success",
"id": 789
}
HTTP Status Code: 200 OK
Success Response (Bulk Contacts)
{
"status": "completed",
"summary": {
"total": 2,
"success": 2,
"failed": 0
},
"results": [
{
"index": 0,
"status": "success",
"id": 789
},
{
"index": 1,
"status": "success",
"id": 790
}
]
}
HTTP Status Code: 200 OK
Error Responses
{
"status": "error",
"message": "Error message details"
}
HTTP Status Code: 400 Bad Request - Missing required fields or invalid data format
401 Unauthorized - Invalid API key
405 Method Not Allowed - Only POST requests are accepted
For bulk operations with partial failures:
{
"status": "completed",
"summary": {
"total": 2,
"success": 1,
"failed": 1
},
"results": [
{
"index": 0,
"status": "success",
"id": 789
},
{
"index": 1,
"status": "error",
"message": "Failed to insert contact",
"error": "Error details"
}
]
}
Notes
The API supports both single contact addition and bulk addition operations.
All contacts are associated with the organization identified by the API key.
Optional fields will use default values if not provided.
When using bulk insertion, the API will process each contact independently and report success/failure for each.
The
created_time
defaults to the current server time if not specified.The
called
andcall_counter
fields default to 0 if not specified.
Limitations
The API requires a valid
campaign_id
that belongs to your organization.All requests must use the POST method; other HTTP methods will be rejected.
The maximum recommended batch size for bulk operations is 500 contacts per request.
Last updated