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

# Campaign contacts and results API

> Upload campaign contacts, browse contacts and call attempts, and download outcome CSV files.

Upload contacts after you create a campaign. A valid upload moves the campaign from `draft` to `ready`.

<ParamField path="account_id" type="string" required>
  Your Vobiz account ID. Use the same value in `X-Auth-ID`.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  The campaign that receives the contacts.
</ParamField>

<ParamField header="X-Auth-ID" type="string" required>
  Your Vobiz account ID, for example `MA_XXXXXXXX`.
</ParamField>

## Endpoints

| Method | Path                                | Description                       |
| ------ | ----------------------------------- | --------------------------------- |
| `POST` | `/campaigns/{campaign_id}/upload`   | Upload a contacts CSV.            |
| `GET`  | `/campaigns/{campaign_id}/contacts` | Browse contacts.                  |
| `GET`  | `/campaigns/{campaign_id}/calls`    | List every call attempt.          |
| `GET`  | `/campaigns/{campaign_id}/results`  | Download contact outcomes as CSV. |

All paths start with `/api/v1/account/{account_id}`.

## Upload contacts

Send `multipart/form-data` with the CSV in a field named `file`.

```bash cURL theme={null}
curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns/{campaign_id}/upload" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -F "file=@contacts.csv"
```

### CSV columns

| Column           | Required                   | Behavior                                         |
| ---------------- | -------------------------- | ------------------------------------------------ |
| `to`             | Always                     | Destination E.164 number.                        |
| `from`           | For `per_contact` strategy | Caller ID for this contact.                      |
| `answer_url`     | No                         | Overrides the agent answer URL for this contact. |
| `hangup_url`     | No                         | Overrides the agent hangup URL for this contact. |
| Any other column | No                         | Sent as a custom SIP header on the call.         |

```csv Fixed strategy theme={null}
to,CustomerID,LeadScore
+919876543210,CUST_001,High
+919876543211,CUST_002,Medium
```

```csv Per-contact strategy theme={null}
to,from,answer_url,CustomerID
+919876543210,+912234567890,https://example.com/answer?id=asha,CUST_001
+919876543211,+912234567891,,CUST_002
```

The streaming parser handles BOM and CRLF line endings. There is no hard row limit, but uploads above 500,000 rows produce an advisory warning.

<Warning>
  Re-uploading on a `ready` campaign replaces every existing contact. Upload is blocked with `409` while a campaign is `running`, `paused`, or `queued`.
</Warning>

```json 200 OK theme={null}
{
  "valid_contacts": 980,
  "invalid_rows": 20,
  "total_rows": 1000,
  "custom_headers_detected": ["CustomerID", "LeadScore"]
}
```

## Browse contacts

Use `limit` and `offset` for pagination. Add `status` to filter by contact state or `search` to find a number.

```http theme={null}
GET /api/v1/account/{account_id}/campaigns/{campaign_id}/contacts?limit=20&offset=0&status=answered
```

The response is `{ objects, total }`.

## List call attempts

Attempts use 1-based `page` pagination. `per_page` has a maximum of `200`. You can filter with `status` or search both the `to` and `from` numbers.

```http theme={null}
GET /api/v1/account/{account_id}/campaigns/{campaign_id}/calls?page=1&per_page=20
```

Campaign-side attempt data is returned even when the CDR service has no matching row. Save a returned `call_uuid` to correlate the attempt with CDRs or call-lookup endpoints.

## Download results

Results are available while the campaign is running, so partial exports are supported.

```bash cURL theme={null}
curl \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns/{campaign_id}/results" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -o campaign-results.csv
```

The CSV columns are:

```text theme={null}
row_number,to_number,from_number_used,status,call_uuid,duration,hangup_cause,attempt_number,answered_at
```

Contact statuses are `pending`, `dialling`, `answered`, `no_answer`, `busy`, `failed`, `retry_pending`, and `expired`.