Add Contacts

Add one or more contacts to an existing campaign. Supports single-contact and bulk modes.

Endpoint

POST https://www.tabbly.io/dashboard/agents/endpoints/add-campaign-contacts

Authentication

See Introduction. This is a POST endpoint — include api_key in the JSON request body.

Request body

Single contact

Parameter	Type	Required	Description
`api_key`	string	Yes	Your organization API key
`phone_number`	string	Yes	Contact phone number (E.164 or local format)
`campaign_id`	integer	Yes	Campaign ID to add the contact to
`participant_identity`	string	No	Contact name or identifier
`use_agent_id`	integer	No	Agent ID for this contact
`created_by`	string	No	Who created this contact (defaults to empty)
`custom_first_line`	string	No	Custom greeting for this contact
`custom_instruction`	string	No	Per-contact agent instructions
`sip_call_id`	string	No	SIP call identifier
`custom_identifiers`	string	No	Key-value mapping for webhooks / call logs. Auto-generated if omitted
`sip_trunk_id`	string	No	SIP trunk ID from List Phone Numbers
`created_time`	string	No	Creation timestamp (defaults to now)
`called`	integer	No	Whether contact has been called (`0` or `1`, default `0`)
`call_counter`	integer	No	Call attempt count (default `0`)

Bulk contacts

Send api_key at the top level and wrap contacts in a contacts array. Each contact object uses the same fields as single mode (except api_key).

Parameter	Type	Required	Description
`api_key`	string	Yes	Your organization API key
`contacts`	array	Yes	Array of contact objects

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",
    "phone_number": "+917219552473",
    "campaign_id": 2744,
    "participant_identity": "John Doe",
    "use_agent_id": 6355,
    "custom_identifiers": "user_id=abc123"
  }'

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",
    "contacts": [
      {
        "phone_number": "+917219552473",
        "campaign_id": 2744,
        "participant_identity": "John Doe",
        "use_agent_id": 6355,
        "custom_identifiers": "user_id=abc123"
      },
      {
        "phone_number": "+918888742268",
        "campaign_id": 2744,
        "participant_identity": "Jane Smith",
        "use_agent_id": 6355,
        "custom_identifiers": "user_id=def456"
      }
    ]
  }'

Response

Single contact — success (200)

{
  "status": "success",
  "id": 3723477,
  "custom_identifier": "user_id=abc123",
  "warning": "Contact added successfully. However, this contact may not trigger a call because the campaign end time has already passed."
}

The warning field is present only when the contact is outside the campaign schedule window.

Bulk — success (200)

{
  "status": "completed",
  "summary": {
    "total": 2,
    "success": 2,
    "failed": 0,
    "warnings": 1
  },
  "results": [
    {
      "index": 0,
      "status": "success",
      "id": 3723479,
      "custom_identifier": "user_id=abc123"
    },
    {
      "index": 1,
      "status": "success",
      "id": 3723480,
      "custom_identifier": "user_id=def456",
      "warning": "Contact added successfully. However..."
    }
  ]
}

Error responses

{
  "status": "error",
  "message": "Human-readable error description"
}

HTTP status	When
200	Success, or error returned in JSON body (`status: "error"`) for invalid key, missing fields, wrong method, etc.
500	Database connection failed (returned in JSON body)

Bulk operations with partial failures return HTTP 200 with per-item error details in results.

Notes

custom_identifiers is auto-generated when omitted.
Phone numbers may be sent with or without a leading +.
Maximum recommended batch size: 500 contacts per request.
The campaign must belong to your organization.