List Campaign Contacts

Retrieve a paginated list of contacts for a specific campaign, with optional status filtering.

Path Parameters

• campaign_id (integer, required): The unique identifier of the campaign

Query Parameters

• page (integer, optional, default: 1): Page number for pagination
• per_page (integer, optional, default: 50, max: 1000): Results per page
• status (string, optional): Filter by contact status

Contact Statuses

Status	Description
pending	Waiting to be contacted
in_progress	Currently being contacted
completed	Successfully contacted
failed	Contact attempt failed
skipped	Skipped (DNC, re-execute filter, etc.)
no_answer	Call not answered
busy	Line was busy
voicemail	Reached voicemail

Response

Response

{
  "contacts": [
    {
      "id": 101,
      "phone_number": "[phone]",
      "contact_data": {
        "company": "Acme Corp",
        "source": "csv_import",
        "variable_values": {
          "name": "John Smith",
          "appointment_date": "2024-02-15"
        },
        "custom_fields": {
          "customer_id": "CUST001"
        }
      },
      "status": "completed",
      "attempts": 1,
      "created_at": "2024-02-01T10:30:00Z",
      "last_attempt_at": "2024-02-01T11:15:00Z"
    },
    {
      "id": 102,
      "phone_number": "[phone]",
      "contact_data": {
        "company": "Tech Inc",
        "source": "csv_import",
        "variable_values": {
          "name": "Jane Doe",
          "appointment_date": "2024-02-16"
        }
      },
      "status": "pending",
      "attempts": 0,
      "created_at": "2024-02-01T10:30:00Z",
      "last_attempt_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_items": 250,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Response Fields

Field	Description
id	Unique contact identifier
phone_number	Contact’s phone number (E.164 format)
contact_data	Contact metadata and custom fields
contact_data.variable_values	Values available for templates
contact_data.custom_fields	Additional imported fields
status	Current contact status
attempts	Number of contact attempts
created_at	When contact was added
last_attempt_at	Last contact attempt timestamp

Example Code

cURL

# Get all contacts
curl -X GET "https://api.burki.dev/api/v1/campaigns/42/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get failed contacts only
curl -X GET "https://api.burki.dev/api/v1/campaigns/42/contacts?status=failed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

# Get all contacts with pagination
response = requests.get(
    "https://api.burki.dev/api/v1/campaigns/42/contacts",
    params={"page": 1, "per_page": 100},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

data = response.json()
for contact in data["contacts"]:
    print(f"{contact['phone_number']}: {contact['status']}")

print(f"Page {data['pagination']['page']} of {data['pagination']['total_pages']}")

JavaScript

// Get pending contacts
const response = await fetch(
  "https://api.burki.dev/api/v1/campaigns/42/contacts?status=pending&per_page=100",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const data = await response.json();
data.contacts.forEach(contact => {
  console.log(`${contact.phone_number}: ${contact.status}`);
});

console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);

Error Responses

Status Code	Description
400	Invalid status value
404	Campaign not found
401	Unauthorized