---
title: "List campaign leads"
method: GET
path: "/api/v4/campaigns/{campaign_id}/leads"
tags: ["Campaigns"]
---

# List campaign leads

`GET /api/v4/campaigns/{campaign_id}/leads`

## Request

- Base URL: `https://{cluster_id}.voiso.com`
- URL: `https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/leads`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/voiso/apis/voiso-api/docs/api/v4/campaigns/:campaign_id/leads/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the campaign leads of the specified campaign, deactivated ones included, in ascending `id` order. Use `metadata.next_cursor` to fetch the next page; it is `null` on the last page. `metadata.total` counts every campaign lead matching the filter, not only the current page.

No change history is stored. To keep a copy in sync, poll with `updated_at[gte]` set to the start time of your previous pull minus 5 minutes and de-duplicate the rows by `id`: a row is stamped before the write that carries it commits, and the overlap catches it. `updated_at` moves on every change to a campaign lead, a new dial attempt and a deactivation included. Pull once a minute per active campaign. This method shares the campaign leads limit of 1000 requests a minute per token with lead create and update; a `429` response means retry after a minute.

Deactivated campaign leads stay listed. When the leads of a stopped or completed campaign are cleaned up, nightly after its dispositions report is downloaded, the method returns an empty list with `total: 0`.

## Path parameters

- `campaign_id` integer, required

## Query parameters

- `limit` integer
- `cursor` string
- `updated_at` union
  - string, date-time
  - RangeFilterDateTime: Date-time range filter with comparison operators.
    - `eq` string, date-time
    - `gt` string, date-time
    - `gte` string, date-time
    - `lt` string, date-time
    - `lte` string, date-time

## Response `200`

OK

- object
  - `campaign_leads` CampaignLead[]: Campaign leads of the page.
    - `id` integer: The unique identifier of the campaign lead. The same value is returned as `campaign_lead_id` in the CDR API and the dialer call event webhooks.
    - `phone_number` string, phone: The phone number of the lead as stored, digits only.
    - `name` string, nullable: The display name of the lead, as sent when the lead was added or updated. `null` when none was sent.
    - `priority` integer, nullable: The lead's priority for calling purposes, as sent when the lead was added or updated. Lower values indicate higher priority. `null` when none was sent: such leads are called last.
    - `active` boolean: Whether the campaign lead is dialled. A campaign lead that was never deactivated reads `true`.
    - `processed` boolean: Whether the dialer has finished with the campaign lead: `true` once the campaign's follow-up rules decided it is not called again, for example after an answered call or the last allowed attempt. Set after the call ends and its wrap-up code is known, so later than the dial attempt itself; `updated_at` moves with it.
    - `dial_attempt_count` integer: The number of dial attempts made to this campaign lead, counted since the counter was introduced.
    - `source` object: Information about the external system that provided the lead, such as a CRM, as sent when the lead was added.
      - `system` string, nullable: External system that provided the lead.
      - `url` string, uri, nullable: URL of the lead in the external system.
    - `import_method` string, nullable: The calling list method of the campaign, as `GET /api/v4/campaigns/{campaign_id}` returns it in `calling_list.method` (`file_import` or a CRM name). It is set per campaign, not per lead: leads added through this API to a file-import campaign read `file_import`. `null` when the campaign has no calling list method.
    - `created_at` string, date-time: When the campaign lead was added. ISO 8601, UTC, with microseconds.
    - `updated_at` string, date-time: When the campaign lead last changed. Moves on every change, a new dial attempt and a deactivation included.
    - `deactivated_at` string, date-time, nullable: When the campaign lead was deactivated; `null` while it is active. Recorded from the release of this method on: campaign leads deactivated earlier keep `null` with `active: false`.
  - `metadata` Metadata: Pagination metadata for list responses.
    - `total` integer: The total number of items available for the requested resource.
    - `next_cursor` string, nullable: Cursor for fetching the next page of results when cursor-based pagination is supported.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Too many requests

## Changes

- **2026-11-03** `5a6ea146bd21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voiso/apis/voiso-api/changes/api/v4/campaigns/:campaign_id/leads/get.md)

---

[API](https://skmtc.dev/voiso/apis/voiso-api.md) - [All operations](https://skmtc.dev/voiso/apis/voiso-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voiso/apis/voiso-api/revisions/5a6ea146bd21?raw)