# List caller IDs

`GET /v1/voice/caller-ids`

Returns a paginated list of the workspace's caller IDs and their verification status.

## Code samples

**TypeScript**

```ts
for await (const callerId of bird.voice.callerIds.list()) {
  console.log(callerId.id, callerId.phone_number, callerId.status);
}
```

Examples: [TypeScript](/docs/api/reference/list-voice-caller-i-ds.ts.md) · [Python](/docs/api/reference/list-voice-caller-i-ds.py.md) · [Go](/docs/api/reference/list-voice-caller-i-ds.go.md) · [PHP](/docs/api/reference/list-voice-caller-i-ds.php.md) · [CLI](/docs/api/reference/list-voice-caller-i-ds.cli.md) · [MCP](/docs/api/reference/list-voice-caller-i-ds.mcp.md) · [cURL](/docs/api/reference/list-voice-caller-i-ds.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "vci_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "phone_number": "+14155551234",
      "name": "Support line",
      "status": "pending",
      "created_at": "2026-05-20T09:14:52Z",
      "updated_at": "2026-05-25T16:42:01Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `sort` (string)

  Field to sort by.

  Possible values: `created_at`
- `order` (string)

  Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

  Possible values: `asc`, `desc`
- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

## Response body

- `data` (array of object, required)
- `data.id` (string, required): Unique identifier for this caller ID.
- `data.workspace_id` (string, required)
- `data.phone_number` (string, required): The phone number in E.164 format registered as a caller ID.
- `data.name` (nullable string, required): Your label for this caller ID, to tell several registered numbers apart. `null` when the caller ID has no label. It is yours to choose and appears nowhere on a call, so changing it never affects what the person you are calling sees. Set it with the caller ID update operation.
- `data.status` (string, required)

  Verification state of the caller ID.

  - `pending`: the number is registered but ownership has not yet been proven.
  - `verified`: the workspace completed the verification call, so the number can
    be presented as the outbound caller ID.
  - `failed`: terminal because the verification challenge expired or the attempt
    limit was exhausted. Use the dashboard to remove and register the caller ID
    again to retry.

  Possible values (may grow over time): `pending`, `verified`, `failed`
- `data.verified_at` (nullable string, required): When the caller ID was verified. `null` when its status is `pending` or `failed`.
- `data.created_at` (string, required)
- `data.updated_at` (string, required)
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)