Add Contacts to Campaign

Crea Contactos de Campaña por lotes. Hasta 1000 contactos por solicitud. Cada item se procesa de forma independiente (una fila inválida no rompe el lote) y se devuelve un summary agregado y results por item. Usa if_duplicate para controlar el comportamiento cuando un contacto ya existe en la campaña (skip mantiene el original, update sobreescribe los campos mutables).

POST /campaigns/{id}/contacts

cURL

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"
}
'

import requests

url = "https://api.altur.io/api/v1.0/campaigns/{id}/contacts"

payload = {
    "contacts": [
        {
            "contact": "<string>",
            "name": "<string>",
            "context": "<string>",
            "extracted_data": {},
            "f_id": "<string>"
        }
    ],
    "if_duplicate": "skip"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contacts: [
      {
        contact: '<string>',
        name: '<string>',
        context: '<string>',
        extracted_data: {},
        f_id: '<string>'
      }
    ],
    if_duplicate: 'skip'
  })
};

fetch('https://api.altur.io/api/v1.0/campaigns/{id}/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.altur.io/api/v1.0/campaigns/{id}/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'contacts' => [
        [
                'contact' => '<string>',
                'name' => '<string>',
                'context' => '<string>',
                'extracted_data' => [
                                
                ],
                'f_id' => '<string>'
        ]
    ],
    'if_duplicate' => 'skip'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.altur.io/api/v1.0/campaigns/{id}/contacts"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"contact\": \"<string>\",\n      \"name\": \"<string>\",\n      \"context\": \"<string>\",\n      \"extracted_data\": {},\n      \"f_id\": \"<string>\"\n    }\n  ],\n  \"if_duplicate\": \"skip\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.altur.io/api/v1.0/campaigns/{id}/contacts")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"contact\": \"<string>\",\n      \"name\": \"<string>\",\n      \"context\": \"<string>\",\n      \"extracted_data\": {},\n      \"f_id\": \"<string>\"\n    }\n  ],\n  \"if_duplicate\": \"skip\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.altur.io/api/v1.0/campaigns/{id}/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contacts\": [\n    {\n      \"contact\": \"<string>\",\n      \"name\": \"<string>\",\n      \"context\": \"<string>\",\n      \"extracted_data\": {},\n      \"f_id\": \"<string>\"\n    }\n  ],\n  \"if_duplicate\": \"skip\"\n}"

response = http.request(request)
puts response.read_body

201

{
  "success": true,
  "summary": {
    "created": 123,
    "updated": 123,
    "skipped_duplicate": 123,
    "failed": 123
  },
  "results": [
    {
      "index": 123,
      "id": "<string>",
      "contact": "<string>",
      "error": "<string>"
    }
  ]
}

{
  "field1": [
    "This field is required."
  ],
  "field2": [
    "Incorrect format."
  ],
  "non_field_errors": [
    "The date range is not valid."
  ]
}

{
  "error": 123,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "field": "<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

Status	Meaning
created	New contact created
updated	Existing contact updated (only when if_duplicate=update)
skipped_duplicate	Existing contact preserved
failed	See error (INVALID_PHONE_NUMBER, MISSING_CONTACT, SERVER_ERROR)

Examples

cURL

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": "[phone]",
        "context": "Past-due 30 days, owes $1200",
        "extracted_data": { "balance": "1200" }
      },
      {
        "f_id": "user_12346",
        "name": "Sofía Pérez",
        "contact": "[phone]"
      }
    ]
  }'

import requests
import uuid

batch = {
    "if_duplicate": "update",
    "contacts": [
        {
            "f_id": "user_12345",
            "name": "John Doe",
            "contact": "[phone]",
            "context": "Past-due 30 days, owes $1200",
            "extracted_data": {"balance": "1200"},
        },
        {
            "f_id": "user_12346",
            "name": "Sofía Pérez",
            "contact": "[phone]",
        },
    ],
}

response = requests.post(
    "https://api.altur.io/api/v1.0/campaigns/1234/contacts",
    headers={
        "Authorization": "api-key YOUR_API_SECRET_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=batch,
)
response.raise_for_status()
body = response.json()
print(body["summary"])  # {"created": 2, "updated": 0, ...}
for item in body["results"]:
    if item["status"] == "failed":
        print(item["index"], item["error"], item["contact"])

const batch = {
  if_duplicate: "update",
  contacts: [
    {
      f_id: "user_12345",
      name: "John Doe",
      contact: "[phone]",
      context: "Past-due 30 days, owes $1200",
      extracted_data: { balance: "1200" },
    },
    { f_id: "user_12346", name: "Sofía Pérez", contact: "[phone]" },
  ],
};

const res = await fetch(
  "https://api.altur.io/api/v1.0/campaigns/1234/contacts",
  {
    method: "POST",
    headers: {
      Authorization: "api-key YOUR_API_SECRET_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(batch),
  },
);
const body = await res.json();
console.log(body.summary);

Example Response

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

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

Show child attributes

if_duplicate · enum<string> · default: skip

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

Available options: skip, update

Response

201

application/json

Batch processed

success · boolean

summary · object

Show child attributes

results · object[]

Show child attributes