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

Parameter	Type	Description	Required
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
sip_trunk_id	String	Specify the SIP Trunk ID from the Phone Numbers section to assign a particular phone number to the contact.	No

2. Bulk Contact Addition

For bulk operations, wrap your contacts in a contacts array:

Parameter	Type	Description	Required
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": "[phone]",
  "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": "[phone]",
    "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": "[phone]",
      "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": "[phone]",
      "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": "[phone]",
        "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": "[phone]",
        "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 and call_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.