> ## Documentation Index > Fetch the complete documentation index at: https://docs.threetone.in/llms.txt > Use this file to discover all available pages before exploring further. # List Phone Numbers Page > Retrieve a page of Phone Numbers ## OpenAPI ````yaml /api-reference/openapi.json get /v1/convai/v2/phone-numbers openapi: 3.1.0 info: title: Threetone API description: >- APIs for the Threetone Agents Platform and shared workspace resources. Authenticate programmatic requests with an API key in the x-api-key header. version: '1.0' servers: - url: https://api.threetone.in description: Production security: [] paths: /v1/convai/v2/phone-numbers: get: tags: - Agents Platform summary: List Phone Numbers Page description: Retrieve a page of Phone Numbers operationId: list_phone_numbers_page_route parameters: - name: page_size in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: Number of phone numbers per page default: 100 title: Page Size description: Number of phone numbers per page - name: search in: query required: false schema: anyOf: - type: string maxLength: 100 - type: 'null' description: >- Filter by phone number ID, label, or phone number. A phone number ID must match exactly; label and phone number matching is a case-insensitive substring. title: Search description: >- Filter by phone number ID, label, or phone number. A phone number ID must match exactly; label and phone number matching is a case-insensitive substring. - name: label in: query required: false schema: anyOf: - type: string maxLength: 100 - type: 'null' description: Filter by label. Matching is a case-insensitive substring. title: Label description: Filter by label. Matching is a case-insensitive substring. - name: phone_number in: query required: false schema: anyOf: - type: string maxLength: 100 - type: 'null' description: Filter by phone number title: Phone Number description: Filter by phone number - name: provider in: query required: false schema: anyOf: - $ref: '#/components/schemas/TelephonyProvider' - type: 'null' description: Filter by telephony provider title: Provider description: Filter by telephony provider - name: supports_outbound in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter by whether the phone number can place outbound calls title: Supports Outbound description: Filter by whether the phone number can place outbound calls - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by assigned agent ID title: Agent Id description: Filter by assigned agent ID - name: branch_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by assigned branch ID title: Branch Id description: Filter by assigned branch ID - name: sort_by in: query required: false schema: anyOf: - $ref: '#/components/schemas/PhoneNumberSortBy' - type: 'null' description: The field to sort the results by title: Sort By description: The field to sort the results by - name: sort_direction in: query required: false schema: $ref: '#/components/schemas/SortDirection' description: The direction to sort the results default: asc description: The direction to sort the results - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Used for fetching next page. Cursor is returned in the response. title: Cursor description: Used for fetching next page. Cursor is returned in the response. - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Your API key for programmatic access. Send it in the x-api-key header; you can create and manage keys from the Developers page. title: X-Api-Key description: >- Your API key for programmatic access. Send it in the x-api-key header; you can create and manage keys from the Developers page. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GetPhoneNumbersPageResponseModel' '422': description: Validation Error content: application/json: schema: anyOf: - $ref: '#/components/schemas/HTTPValidationError' - $ref: '#/components/schemas/APIErrorResponse' title: Response 422 List Phone Numbers Page Route default: description: >- API error. Depending on the operation: 400 invalid request, 401 authentication required, 402 insufficient credits, 403 permission denied, 404 resource not found, 409 conflict, 429 rate limit, 500 internal failure, 502 upstream failure, 503 service unavailable, or 504 upstream timeout. A failed response does not establish whether a state-changing operation completed; do not retry such operations without checking their outcome. headers: X-Request-Id: description: Request identifier, when available. schema: type: string Retry-After: description: >- When supplied, the delay in seconds or HTTP date before a subsequent request. schema: type: string content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' components: schemas: TelephonyProvider: type: string enum: - twilio - sip_trunk - exotel title: TelephonyProvider PhoneNumberSortBy: type: string enum: - label - phone_number title: PhoneNumberSortBy SortDirection: type: string enum: - asc - desc title: SortDirection GetPhoneNumbersPageResponseModel: properties: phone_numbers: items: oneOf: - $ref: '#/components/schemas/GetPhoneNumberTwilioResponseModel' - $ref: '#/components/schemas/GetPhoneNumberExotelResponseModel' - $ref: '#/components/schemas/GetPhoneNumberSIPTrunkResponseModel' discriminator: propertyName: provider mapping: exotel: '#/components/schemas/GetPhoneNumberExotelResponseModel' sip_trunk: '#/components/schemas/GetPhoneNumberSIPTrunkResponseModel' twilio: '#/components/schemas/GetPhoneNumberTwilioResponseModel' type: array title: Phone Numbers description: The phone numbers on this page next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: >- Pass this value as `cursor` to fetch the next page. Null when there are no more results. has_more: type: boolean title: Has More description: Whether there are more results available default: false type: object required: - phone_numbers title: GetPhoneNumbersPageResponseModel HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError APIErrorResponse: properties: detail: $ref: '#/components/schemas/APIErrorDetail' type: object required: - detail title: APIErrorResponse GetPhoneNumberTwilioResponseModel: properties: phone_number: type: string title: Phone Number description: Phone number label: type: string title: Label description: Label for the phone number phone_number_id: type: string title: Phone Number Id description: The ID of the phone number assigned_agent: anyOf: - $ref: '#/components/schemas/PhoneNumberAgentInfo' - type: 'null' description: The agent that is assigned to the phone number provider: type: string const: twilio title: Provider description: Phone provider default: twilio type: object required: - phone_number - label - phone_number_id title: GetPhoneNumberTwilioResponseModel example: label: Customer Support phone_number: '+1234567890' phone_number_id: phone_123 provider: twilio GetPhoneNumberExotelResponseModel: properties: phone_number: type: string title: Phone Number description: Phone number label: type: string title: Label description: Label for the phone number phone_number_id: type: string title: Phone Number Id description: The ID of the phone number assigned_agent: anyOf: - $ref: '#/components/schemas/PhoneNumberAgentInfo' - type: 'null' description: The agent that is assigned to the phone number provider: type: string const: exotel title: Provider description: Phone provider default: exotel type: object required: - phone_number - label - phone_number_id title: GetPhoneNumberExotelResponseModel example: label: Exotel Outbound phone_number: '+919999999999' phone_number_id: phnum_X3Pbu5gP6NNKBscdCdwB provider: exotel GetPhoneNumberSIPTrunkResponseModel: properties: phone_number: type: string title: Phone Number description: Phone number label: type: string title: Label description: Label for the phone number phone_number_id: type: string title: Phone Number Id description: The ID of the phone number assigned_agent: anyOf: - $ref: '#/components/schemas/PhoneNumberAgentInfo' - type: 'null' description: The agent that is assigned to the phone number provider: type: string const: sip_trunk title: Provider description: Phone provider default: sip_trunk source_type: type: string const: sip_trunk title: Source Type description: Phone number source type default: sip_trunk outbound_trunk: anyOf: - $ref: >- #/components/schemas/GetPhoneNumberOutboundSIPTrunkConfigResponseModel - type: 'null' description: Configuration of the Outbound SIP trunk - if configured. inbound_trunk: anyOf: - $ref: >- #/components/schemas/GetPhoneNumberInboundSIPTrunkConfigResponseModel - type: 'null' description: Configuration of the Inbound SIP trunk - if configured. livekit_stack: $ref: '#/components/schemas/LivekitStackType' description: Type of Livekit stack used for this number. store_sip_messages: type: boolean title: Store Sip Messages description: Whether to store SIP messages for this phone number. default: true type: object required: - phone_number - label - phone_number_id - livekit_stack title: GetPhoneNumberSIPTrunkResponseModel description: >- SIP-trunk-backed phone number row. Inbound/outbound capability is implied by `inbound_trunk` / `outbound_trunk` (and related flags), not by separate booleans. example: label: Sales Team livekit_stack: standard phone_number: '+1987654321' phone_number_id: phone_456 source_type: sip_trunk ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError APIErrorDetail: properties: status: type: string title: Status description: >- Stable application error identifier, separate from the HTTP status code. message: type: string title: Message description: Customer-facing explanation of the error. request_id: anyOf: - type: string - type: 'null' title: Request Id description: Request identifier for support and troubleshooting, when available. additionalProperties: true type: object required: - status - message title: APIErrorDetail description: Public error fields; domains may supply additional customer-safe detail. PhoneNumberAgentInfo: properties: agent_id: type: string title: Agent Id description: The ID of the agent agent_name: type: string title: Agent Name description: The name of the agent environment: anyOf: - type: string - type: 'null' title: Environment description: >- Environment to use for resolving environment variables on calls to this number. branch_id: anyOf: - type: string - type: 'null' title: Branch Id description: Agent branch to use for calls to this number. type: object required: - agent_id - agent_name title: PhoneNumberAgentInfo example: agent_id: F3Pbu5gP6NNKBscdCdwB agent_name: My Agent GetPhoneNumberOutboundSIPTrunkConfigResponseModel: properties: address: type: string title: Address description: Hostname or IP the SIP INVITE is sent to transport: $ref: '#/components/schemas/SIPTrunkTransportEnum' description: Protocol to use for SIP transport media_encryption: $ref: '#/components/schemas/SIPMediaEncryptionEnum' description: Whether or not to encrypt media (data layer). headers: additionalProperties: type: string type: object title: Headers description: SIP headers for INVITE request attributes_to_headers: additionalProperties: type: string type: object title: Attributes To Headers description: >- Map of dynamic variable name to header name for attributes_to_headers has_auth_credentials: type: boolean title: Has Auth Credentials description: Whether authentication credentials are configured username: anyOf: - type: string - type: 'null' title: Username description: SIP trunk username (if available) has_outbound_trunk: type: boolean title: Has Outbound Trunk description: Whether a LiveKit SIP outbound trunk is configured default: false enabled_codecs: items: $ref: '#/components/schemas/MediaCodec' type: array title: Enabled Codecs description: >- Media codecs that are offered in the SDP for outbound calls. If empty, all supported codecs are offered. type: object required: - address - transport - media_encryption - has_auth_credentials title: GetPhoneNumberOutboundSIPTrunkConfigResponseModel description: SIP Trunk configuration details for a phone number GetPhoneNumberInboundSIPTrunkConfigResponseModel: properties: allowed_addresses: items: type: string type: array title: Allowed Addresses description: >- List of IP addresses that are allowed to use the trunk. Each item in the list can be an individual IP address or a Classless Inter-Domain Routing notation representing a CIDR block. allowed_numbers: anyOf: - items: type: string type: array - type: 'null' title: Allowed Numbers description: List of phone numbers that are allowed to use the trunk. media_encryption: $ref: '#/components/schemas/SIPMediaEncryptionEnum' has_auth_credentials: type: boolean title: Has Auth Credentials description: Whether authentication credentials are configured username: anyOf: - type: string - type: 'null' title: Username description: SIP trunk username (if available) remote_domains: anyOf: - items: type: string type: array - type: 'null' title: Remote Domains description: Domains of remote SIP servers used to validate TLS certificates. attributes_to_headers: additionalProperties: type: string type: object title: Attributes To Headers description: >- Map of dynamic variable name to header name for attributes_to_headers type: object required: - allowed_addresses - allowed_numbers - media_encryption - has_auth_credentials title: GetPhoneNumberInboundSIPTrunkConfigResponseModel LivekitStackType: type: string enum: - standard - static title: LivekitStackType SIPTrunkTransportEnum: type: string enum: - auto - udp - tcp - tls title: SIPTrunkTransportEnum SIPMediaEncryptionEnum: type: string enum: - disabled - allowed - required title: SIPMediaEncryptionEnum MediaCodec: type: string enum: - G722/8000 - PCMU/8000 - PCMA/8000 title: MediaCodec ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.