Skip to main content
POST
/
campaigns
/
{id}
/
contacts
cURL
curl --request POST \
  --url https://api.altur.io/api/v1.0/campaigns/{id}/contacts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "contact": "<string>",
      "name": "<string>",
      "context": "<string>",
      "extracted_data": {},
      "f_id": "<string>"
    }
  ],
  "if_duplicate": "skip"
}
'
{
  "success": true,
  "summary": {
    "created": 123,
    "updated": 123,
    "skipped_duplicate": 123,
    "failed": 123
  },
  "results": [
    {
      "index": 123,
      "id": "<string>",
      "contact": "<string>",
      "error": "<string>"
    }
  ]
}
Rate Limit: 12 requests per second
Up to 1000 contacts per request. Each item is processed independently, so one bad row does not fail the batch. The response includes an aggregate summary plus per-item results.
Pass an Idempotency-Key header (UUID recommended) so retries don’t enqueue duplicate batches.

​
Duplicate Handling

if_duplicate controls behavior when the contact’s phone number already exists in the campaign:
  • skip (default): keep the existing contact, return skipped_duplicate.
  • update: overwrite name, context, extracted_data, and f_id on the existing contact, return updated.

​
Per-item Result Statuses

StatusMeaning
createdNew contact created
updatedExisting contact updated (only when if_duplicate=update)
skipped_duplicateExisting contact preserved
failedSee error (INVALID_PHONE_NUMBER, MISSING_CONTACT, SERVER_ERROR)

​
Examples

curl -X POST "https://api.altur.io/api/v1.0/campaigns/1234/contacts" \
  -H "Authorization: api-key YOUR_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c1a45e88-ad34-4f57-9d2e-91a1d4f50f7e" \
  -d '{
    "if_duplicate": "update",
    "contacts": [
      {
        "f_id": "user_12345",
        "name": "John Doe",
        "contact": "+521234567890",
        "context": "Past-due 30 days, owes $1200",
        "extracted_data": { "balance": "1200" }
      },
      {
        "f_id": "user_12346",
        "name": "Sofía Pérez",
        "contact": "+529876543210"
      }
    ]
  }'

​
Example Response

{
  "success": true,
  "summary": { "created": 2, "updated": 0, "skipped_duplicate": 0, "failed": 0 },
  "results": [
    { "index": 0, "status": "created", "id": "42", "contact": "+521234567890" },
    { "index": 1, "status": "created", "id": "43", "contact": "+529876543210" }
  ]
}

Authorizations

​
Authorization
string
header
required

Add api-key YOUR_API_SECRET_KEY as the value of the Authorization header.

Headers

​
Idempotency-Key
string

Optional client-generated key (UUID recommended) to make the request idempotent.

Path Parameters

​
id
integer
required

The identifier of the Campaign

Body

application/json

Batch of contacts to create

​
contacts
object[]
required
Required array length: 1 - 1000 elements
​
if_duplicate
enum<string>
default:skip

Behavior when the contact's phone number already exists in this campaign.

Available options:
skip,
update

Response

Batch processed

​
success
boolean
​
summary
object
​
results
object[]