Skip to main content

​
Add Contacts to Campaign

​
Overview

This endpoint enables bulk addition of contacts to a specified campaign. Each contact can include basic information and optional metadata.

​
Endpoint Details

  • URL: /contacts/addToCampaign/{campaign_id}
  • Method: POST
  • Authentication: Required (User authentication API KEY)

​
Path Parameters

ParameterTypeRequiredDescription
campaign_idUUIDYesThe unique identifier of the target campaign

​
Request Headers

HeaderValueDescription
AuthorizationBearer <api_key>Your API KEY
Content-Typeapplication/jsonRequest body format

​
Request Body

An array of contact objects with the following structure: 
[
  {
    "firstname": "string",
    "lastname": "string",
    "phone_number": "string",
    "metadata": {
      // Optional custom key-value pairs
    }
  }
]

​
Request Body Parameters

ParameterTypeRequiredDescription
firstnamestringYesContact’s first name
lastnamestringYesContact’s last name
phone_numberstringYesContact’s phone number
metadataobjectNoAdditional custom data for the contact

​
Response

​
Success Response

  • Status Code: 200 OK
{
  "status": "ok",
  "message": "ok",
  "data": <contact_data>
}

​
Error Response

  • Status Code: 200 OK (with error message)
{
  "status": "error",
  "message": "error",
  "data": ""
}

​
Example Request

curl -X POST \
  'https://api.callab.ai/compaign/v1/contacts/addToCampaign/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "firstname": "John",
      "lastname": "Doe",
      "phone_number": "+1234567890",
      "metadata": {
        "source": "web",
        "tags": ["vip", "new-customer"]
      }
    }
  ]'

​
Notes

  • The endpoint validates the company ID from the user’s authentication api_key
  • All contacts in the array must contain the required fields
  • The campaign must exist and belong to the authenticated user’s company
  • Metadata is optional and can contain any valid JSON object
  • The phone number format should be consistent with your system’s requirements

​
Error Handling

The API will return appropriate error messages for the following scenarios:
  • Invalid campaign ID
  • Unauthorized access
  • Invalid contact data format
  • Database operation failures
⌘I