# 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

```json
{
  "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)

```bash
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

```json
{
  "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)

```bash
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)

```json
{
  "status": "success",
  "id": 789
}
```

HTTP Status Code: 200 OK

#### Success Response (Bulk Contacts)

```json
{
  "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

```json
{
  "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:

```json
{
  "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.
