Add Contacts

Adds phone numbers (contacts) to an existing campaign so they can be dialed. 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	Customer phone number to be called by the campaign (E.164 or local format)
`campaign_id`	integer	Yes	Campaign ID to add the contact to
`created_by`	string	No	Optional label for who added the contact (for your own tracking; defaults to empty)
`custom_first_line`	string	No	Custom greeting for this contact
`custom_instruction`	string	No	Per-contact agent instructions
`custom_identifiers`	string	No	Optional tag for this contact (e.g. `user_id=abc123`). Shown in call logs and webhooks. Auto-generated if omitted
`sip_trunk_id`	string	No	Optional. SIP trunk for this contact’s outbound call. Get it from List Phone Numbers

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 request

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": "+912269858803",
    "campaign_id": 2744,
    "custom_identifiers": "user_id=abc123"
  }'

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": "+912269858803",
        "campaign_id": 2744,
        "custom_identifiers": "user_id=abc123"
      },
      {
        "phone_number": "+912269852098",
        "campaign_id": 2744,
        "custom_identifiers": "user_id=def456"
      }
    ]
  }'

Response

Success (200) — single contact

{
  "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."
}

Field	Type	Description
`id`	string	Contact record ID
`custom_identifier`	string	Value stored for `custom_identifiers` (singular in response)

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

Success (200) — bulk

{
  "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..."
    }
  ]
}

summary.warnings is included only when at least one contact has a schedule warning. When custom_identifiers is omitted, the API auto-generates a unique string for custom_identifier.

Error responses

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

HTTP status	When
200	Success, or application error in JSON body: invalid API key, missing fields, wrong method
500	Database connection failed (returned in JSON body)

Always check the status field in the response body — do not rely on HTTP status alone for this endpoint.

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.