> ## Documentation Index > Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt > Use this file to discover all available pages before exploring further. # List phone numbers > Retrieve a paginated list of the phone numbers configured in your account. Use `page_size` and `page_token` to page through the list. By default only `ACTIVE` phone numbers are returned, sorted by creation time in ascending order. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/phone-numbers/ openapi: 3.1.0 info: title: Verbex Platform API description: API for managing AI agents, calls, phone numbers, and more. version: 1.0.0 servers: [] security: [] tags: - name: Knowledge Bases description: >- Create and manage knowledge bases, ingest documents into them, and search them semantically. **Authentication.** Every request carries a bearer token: `Authorization: Bearer `. That is the only credential a client sends. The gateway resolves your identity from it and injects the tenant headers the service reads internally, so clients never send `x-user-org-id` or `x-verbex-id` themselves. **Tenancy is enforced on every route.** A knowledge base belongs to one organization and one user. Requesting one your token does not own returns `404 Knowledge base not found`, never `403`. This is deliberate: a nonexistent ID, a malformed ID and someone else's ID are indistinguishable in the response, so the API cannot be used to probe for other tenants' data. If you get a `404` on an ID you are certain exists, suspect the token before you suspect the ID. **Ingestion is asynchronous.** File upload and website crawl both answer `202` as soon as the material is stored and the job is queued. Parsing, chunking, embedding and indexing happen afterwards in a worker. Poll the document status endpoint until it reports `completed` before expecting search to see the content. That gap is the most common source of "why isn't my data showing up". **There is no document update endpoint.** Every submission mints a new `document_id`, so re-uploading a file or re-crawling the same URLs creates a second document while the first remains. To refresh material, delete then resubmit — and note that the sequence is not atomic. - name: AI Agents v3 description: >- Create, read, update and delete AI agents. v3 selects the LLM, speech-to-text model and voice by catalog id, and wraps every response in a standard envelope. It replaces the deprecated AI Agents v2 operations, which stop working on November 30, 2026. See [Migrate from v2 to v3](/api-reference/ai-agents-v3/migrate-from-v2). - name: LLM Models description: >- The LLM model catalog. Look up the `llm_model_id` to send as `llm.llm_id` when you create or update an agent. - name: Speech Providers description: >- The speech-to-text and text-to-speech provider catalogs. Look up the `provider_id`, `model_id` and `voice_id` to send when you create or update an agent. paths: /v1/phone-numbers/: get: tags: - Phone Numbers summary: List phone numbers description: >- Retrieve a paginated list of the phone numbers configured in your account. Use `page_size` and `page_token` to page through the list. By default only `ACTIVE` phone numbers are returned, sorted by creation time in ascending order. operationId: list_phone_numbers_v1_phone_numbers__get parameters: - name: page_size in: query required: false description: Number of phone numbers per page schema: type: integer minimum: 1 default: 20 title: Page Size - name: page_token in: query required: false schema: anyOf: - type: string - type: 'null' title: Page Token description: >- Token from `next_page_token` of the previous response, to fetch the next page - name: sort_direction in: query required: false description: Sort order by creation time schema: type: string enum: - asc - desc default: asc title: Sort Direction - name: phoneStatus in: query required: false description: Filter by phone number status schema: type: string enum: - ACTIVE - INACTIVE - DELETED default: ACTIVE title: Phone Status responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PhoneNumberListResponse' '400': description: >- Bad request - a query parameter has an invalid value (for example `phoneStatus` not one of `ACTIVE`, `INACTIVE`, `DELETED`, or a non-numeric `page_size`). content: application/json: schema: $ref: >- #/components/schemas/app__phone_numbers__schemas__ErrorResponse example: status: 400 type: BAD_REQUEST message: Parameter 'phoneStatus' has an invalid value trace_id: 341b5325-a0be-4533-85dd-6f697476dfc3 timestamp: '2026-11-01T10:00:00Z' path: /v1/phone-numbers '401': description: Unauthorized - missing or invalid API key (returned by the gateway). content: application/json: schema: $ref: '#/components/schemas/GatewayAuthErrorResponse' '500': description: >- Internal server error, including SIP provisioning failures (`KAMAILIO_SYNC_ERROR`). Partial changes are rolled back. content: application/json: schema: $ref: >- #/components/schemas/app__phone_numbers__schemas__ErrorResponse examples: internal: value: status: 500 type: INTERNAL_ERROR message: An unexpected error occurred trace_id: 341b5325-a0be-4533-85dd-6f697476dfc3 timestamp: '2026-11-01T10:00:00Z' path: /v1/phone-numbers kamailio: value: status: 500 type: KAMAILIO_SYNC_ERROR message: Failed to provision Kamailio SIP tables trace_id: 341b5325-a0be-4533-85dd-6f697476dfc3 timestamp: '2026-11-01T10:00:00Z' path: /v1/phone-numbers components: schemas: PhoneNumberListResponse: properties: phone_numbers: items: $ref: '#/components/schemas/GetSIPPhoneNumberResponse' type: array title: Phone Numbers description: List of phone number records matching the query parameters next_page_token: anyOf: - type: string - type: 'null' title: Next Page Token description: >- Token for retrieving the next page of results. Null if there are no more results type: object required: - phone_numbers title: PhoneNumberListResponse app__phone_numbers__schemas__ErrorResponse: properties: status: type: integer title: Status description: HTTP status code type: type: string title: Type description: |- Error type. Each type always maps to the same HTTP status: | HTTP | `type` | |---|---| | 400 | `BAD_REQUEST` | | 404 | `NOT_FOUND`, `PHONE_NOT_FOUND`, `AGENT_NOT_FOUND` | | 409 | `PHONE_ALREADY_EXISTS`, `CONFLICT` | | 422 | `VALIDATION_ERROR`, `MISSING_REQUIRED_FIELD` | | 500 | `INTERNAL_ERROR`, `KAMAILIO_SYNC_ERROR` | enum: - VALIDATION_ERROR - MISSING_REQUIRED_FIELD - NOT_FOUND - PHONE_NOT_FOUND - AGENT_NOT_FOUND - CONFLICT - PHONE_ALREADY_EXISTS - BAD_REQUEST - KAMAILIO_SYNC_ERROR - INTERNAL_ERROR message: type: string title: Message description: Human-readable error message trace_id: type: string title: Trace Id description: Trace identifier to share with support details: type: object title: Details description: >- Additional error details. For body validation errors it holds `fields` (field name -> message). Omitted when empty. timestamp: type: string format: date-time title: Timestamp description: When the error occurred (UTC) path: type: string title: Path description: Request path that produced the error type: object required: - status - type - message title: PhoneNumberErrorResponse example: status: 422 type: VALIDATION_ERROR message: >- Invalid phone number format: '12'. Must be an optional '+' followed by 3 to 20 digits (e.g., +1234567890 or 999) timestamp: '2026-11-01T10:00:00Z' path: /v1/phone-numbers GatewayAuthErrorResponse: type: object title: GatewayAuthErrorResponse description: >- Returned by the API gateway when the API key is missing or invalid (the request never reaches the service). properties: error: type: string title: Error example: Authentication message: type: string title: Message example: Authentication failed traceId: type: string title: Trace Id example: e679120f-1d1c-41d2-947c-34e194d5a4a1 GetSIPPhoneNumberResponse: properties: _id: type: string title: Id description: Unique identifier for this phone number record provider: type: string const: sip title: Provider description: Phone number provider phone_number: type: string title: Phone Number description: The phone number friendly_name: anyOf: - type: string - type: 'null' title: Friendly Name description: >- A human-readable label for this phone number. Cannot be blank when provided. sip_termination_uri: anyOf: - type: string - type: 'null' title: Sip Termination Uri description: >- The SIP URI that outbound calls are sent to. The host must be an IP address or domain. Optional for inbound-only numbers. sip_trunk_username: anyOf: - type: string - type: 'null' title: Sip Trunk Username description: Username for authenticating with the SIP trunk provider sip_trunk_password: anyOf: - type: string - type: 'null' title: Sip Trunk Password description: Password for authenticating with the SIP trunk provider inbound_agent_id: anyOf: - type: string - type: 'null' title: Inbound Agent Id description: >- ID of the AI agent that handles incoming calls to this number. Cannot be blank when provided. outbound_agent_id: anyOf: - type: string - type: 'null' title: Outbound Agent Id description: >- ID of the AI agent used for outbound calls from this number. Cannot be blank when provided. sip_infra_region: anyOf: - type: string - type: 'null' title: Sip Infra Region description: The infrastructure region for SIP routing sip_infra_zones: anyOf: - type: array items: type: string - type: 'null' title: Sip Infra Zones description: >- Zones within a multi-zone `sip_infra_region` to register the number on. The zones that come up are returned as `availability_zones`. Only for organizations with multi-zone routing enabled. call_concurrency: anyOf: - type: integer minimum: 1 - type: 'null' title: Call Concurrency description: Maximum number of concurrent calls allowed on this number max_concurrent_inbound_calls: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Concurrent Inbound Calls description: Maximum number of concurrent inbound calls max_concurrent_outbound_calls: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Concurrent Outbound Calls description: Maximum number of concurrent outbound calls expires: anyOf: - type: integer minimum: 1 - type: 'null' title: Expires description: SIP registration expiry, in seconds advanced: anyOf: - $ref: '#/components/schemas/AdvancedSipConfig' - type: 'null' title: Advanced description: Advanced SIP configuration availability_zones: anyOf: - type: array items: type: string - type: 'null' title: Availability Zones description: >- Zones the number is registered and available on. Omitted when not set. workspace_id: anyOf: - type: string - type: 'null' title: Workspace Id description: Workspace the phone number belongs to type: object required: - phone_number title: GetSIPPhoneNumberResponse x-unpublished-properties: _note: Hidden until published. To publish, move these back into `properties`. inbound_sip_headers: anyOf: - $ref: '#/components/schemas/SipHeaderConfig' - type: 'null' title: Inbound Sip Headers description: Custom inbound SIP header configuration AdvancedSipConfig: type: object title: AdvancedSipConfig description: Advanced SIP configuration properties: realm: anyOf: - type: string - type: 'null' title: Realm description: >- SIP realm. Defaults to the SIP domain when empty. Cannot be blank when provided. examples: - asterisk ip: anyOf: - type: string - type: 'null' title: Ip description: Carrier IP address or CIDR to allow (e.g. `1.2.3.4/24`) examples: - 1.2.3.4/24 prefix: anyOf: - type: string pattern: ^\d+$ - type: 'null' title: Prefix description: Dial prefix (digits only) prepended to the outbound trunk username examples: - '0' register: anyOf: - type: boolean default: true - type: 'null' title: Register description: Whether to register outbound to the carrier ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.