> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burki.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Campaign Contacts

> Get paginated list of contacts for a campaign.

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

```json Response theme={null}
{
  "contacts": [
    {
      "id": 101,
      "phone_number": "+15551234567",
      "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": "+15559876543",
      "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

```bash cURL theme={null}
# 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 Python theme={null}
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 JavaScript theme={null}
// 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         |


## OpenAPI

````yaml GET /api/v1/campaigns/{campaign_id}/contacts
openapi: 3.1.0
info:
  title: Burki
  description: A system that uses AI to answer customer Calls.
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/campaigns/{campaign_id}/contacts:
    get:
      tags:
        - campaigns
      summary: Get Campaign Contacts
      description: Get paginated list of contacts for a campaign.
      operationId: get_campaign_contacts_api_v1_campaigns__campaign_id__contacts_get
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: integer
            title: Campaign Id
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            title: Page
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            default: 50
            title: Per Page
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````