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

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": "+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 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.

Last updated