---
title: "GET /phone/identities"
method: GET
path: "/phone/identities"
---

# GET /phone/identities

`GET /phone/identities`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/phone/identities`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Query parameters

- `cursor` string: Opaque cursor from a previous response to fetch the next page
- `limit` integer: Maximum number of items to return per page (1–100, default 20)
- `query` string: Free-text search. Digits match the number itself, ignoring punctuation and spacing; the raw term also matches the owning agent's name or slug.
- `agentId` union: Restrict to one agent's numbers. Omit to list every number in the organization. An agent key is confined to its own numbers whether or not this is set.
  - string
  - string

## Response `200`

OK

- object: Paginated list of phone numbers across an organization
  - `items` object[], required: Phone identities matching the query, with their owning agent
    - `id` string, required: Unique identifier of the phone identity
    - `phoneNumber` string, required: Phone number in E.164 format
    - `providerId` string, nullable, required: Opaque carrier-side identifier for this phone number
    - `capabilities` object, required: Communication capabilities supported by this phone number
      - `sms` boolean: Whether the number supports SMS messaging
      - `mms` boolean: Whether the number supports MMS messaging
      - `voice` boolean: Whether the number supports voice calls
    - `tenDlcStatus` 'PENDING' | 'REGISTERED' | 'REJECTED' | 'NOT_REQUIRED' | 'UNREGISTERED', required: 10DLC campaign registration status
    - `isPrimary` boolean, required: Whether this is the agent's primary phone identity
    - `voiceId` string, nullable, required: The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different.
    - `createdAt` string, date-time, required: Timestamp when the phone identity was created
    - `agentId` string, required: Agent that owns the number
    - `agentName` string, required: Name of the agent that owns the number
    - `agentSlug` string, required: Slug of the agent that owns the number
  - `pagination` object, required: Cursor-based pagination metadata
    - `nextCursor` string, nullable, required: Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results
    - `hasMore` boolean, required: Whether additional pages of results are available

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)