> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # List phone numbers ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/numbers-identity/management-config.yml get /phone_numbers openapi: 3.1.0 info: title: Telnyx Phone Number Management API version: 2.0.0 description: API for managing and configuring phone numbers. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] paths: /phone_numbers: get: tags: - Phone Number Configurations summary: List phone numbers operationId: ListPhoneNumbers parameters: - $ref: '#/components/parameters/numbers_PageConsolidated' - name: sort in: query description: >- Specifies the sort order for results. If not given, results are sorted by created_at in descending order. required: false schema: type: string enum: - purchased_at - phone_number - connection_name - usage_payment_method example: connection_name - name: filter in: query style: deepObject explode: true description: >- Consolidated filter parameter (deepObject style). Originally: filter[tag], filter[phone_number], filter[status], filter[country_iso_alpha2], filter[connection_id], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference], filter[number_type], filter[source] schema: type: object properties: tag: type: string description: Filter by phone number tags. without_tags: type: string description: >- When set to 'true', filters for phone numbers that do not have any tags applied. All other values are ignored. enum: - 'true' - 'false' phone_number: type: string description: |- Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned. status: type: string enum: - purchase-pending - purchase-failed - port-pending - active - deleted - port-failed - emergency-only - ported-out - port-out-pending example: active description: Filter by phone number status. country_iso_alpha2: oneOf: - type: string example: US - type: array items: type: string example: - US - CA description: >- Filter by phone number country ISO alpha-2 code. Can be a single value or an array of values. connection_id: type: string example: '1521916448077776306' description: Filter by connection_id. voice.connection_name: type: object description: Filter by voice connection name pattern matching. properties: contains: type: string example: test description: >- Filter contains connection name. Requires at least three characters. starts_with: type: string example: test description: >- Filter starts with connection name. Requires at least three characters. ends_with: type: string example: test description: >- Filter ends with connection name. Requires at least three characters. eq: type: string example: test description: Filter by connection name. additionalProperties: false voice.usage_payment_method: type: string enum: - pay-per-minute - channel example: channel description: Filter by usage_payment_method. billing_group_id: type: string example: 62e4bf2e-c278-4282-b524-488d9c9c43b2 description: >- Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'. emergency_address_id: type: string example: '9102160989215728032' description: >- Filter by the emergency_address_id associated with phone numbers. To filter only phone numbers that have no emergency address associated with them, set the value of this filter to the string 'null'. customer_reference: type: string description: Filter numbers via the customer_reference set. number_type: type: object description: Filter phone numbers by phone number type. properties: eq: type: string enum: - local - national - toll_free - mobile - shared_cost description: Filter phone numbers by phone number type. additionalProperties: false source: type: string enum: - ported - purchased description: >- Filter phone numbers by their source. Use 'ported' for numbers ported from other carriers, or 'purchased' for numbers bought directly from Telnyx. - name: handle_messaging_profile_error in: query description: >- Although it is an infrequent occurrence, due to the highly distributed nature of the Telnyx platform, it is possible that there will be an issue when loading in Messaging Profile information. As such, when this parameter is set to `true` and an error in fetching this information occurs, messaging profile related fields will be omitted in the response and an error message will be included instead of returning a 503 error. schema: type: string enum: - 'true' - 'false' example: 'false' default: 'false' responses: '200': $ref: '#/components/responses/ListPhoneNumbersResponse' '400': $ref: '#/components/responses/numbers_BadRequestResponse' '401': $ref: '#/components/responses/numbers_UnauthorizedResponse' '404': $ref: '#/components/responses/numbers_NotFoundResponse' '422': $ref: '#/components/responses/numbers_UnprocessableEntity' '500': $ref: '#/components/responses/numbers_GenericErrorResponse' x-codeSamples: - lang: JavaScript source: >- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const phoneNumberDetailed of client.phoneNumbers.list()) { console.log(phoneNumberDetailed.id); } - lang: Python source: |- import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) page = client.phone_numbers.list() page = page.data[0] print(page.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.PhoneNumbers.List(context.TODO(), telnyx.PhoneNumberListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.phonenumbers.PhoneNumberListPage; import com.telnyx.sdk.models.phonenumbers.PhoneNumberListParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); PhoneNumberListPage page = client.phoneNumbers().list(); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") page = telnyx.phone_numbers.list puts(page) - lang: PHP source: >- phoneNumbers->list( filter: [ 'billingGroupID' => '62e4bf2e-c278-4282-b524-488d9c9c43b2', 'connectionID' => '1521916448077776306', 'countryISOAlpha2' => 'US', 'customerReference' => 'customer_reference', 'emergencyAddressID' => '9102160989215728032', 'numberType' => ['eq' => 'local'], 'phoneNumber' => 'phone_number', 'source' => 'ported', 'status' => 'active', 'tag' => 'tag', 'voiceConnectionName' => [ 'contains' => 'test', 'endsWith' => 'test', 'eq' => 'test', 'startsWith' => 'test', ], 'voiceUsagePaymentMethod' => 'channel', 'withoutTags' => 'true', ], handleMessagingProfileError: 'false', pageNumber: 0, pageSize: 0, sort: 'connection_name', ); var_dump($page); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx phone-numbers list \ --api-key 'My API Key' components: parameters: numbers_PageConsolidated: name: page in: query style: deepObject explode: true description: >- Consolidated page parameter (deepObject style). Originally: page[size], page[number] schema: type: object properties: size: type: integer minimum: 1 maximum: 250 default: 20 description: The size of the page number: type: integer minimum: 1 default: 1 description: The page number to load responses: ListPhoneNumbersResponse: description: Successful response with a list of phone numbers. content: application/json: schema: type: object title: List Phone Numbers Response required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/PhoneNumberDetailed' meta: $ref: '#/components/schemas/PaginationMeta' errors: type: array items: $ref: '#/components/schemas/numbers_Error' numbers_BadRequestResponse: description: >- Bad request, the request was unacceptable, often due to missing a required parameter. content: application/json: schema: $ref: '#/components/schemas/numbers_Errors' numbers_UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/numbers_Errors' examples: Authentication Failed: value: errors: - code: '10009' title: Authentication failed detail: Could not understand the provided credentials. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 numbers_NotFoundResponse: description: The requested resource doesn't exist. content: application/json: schema: $ref: '#/components/schemas/numbers_Errors' numbers_UnprocessableEntity: description: Unprocessable entity. Check the 'detail' field in response for details. content: application/json: schema: $ref: '#/components/schemas/numbers_Errors' numbers_GenericErrorResponse: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/numbers_Errors' schemas: PhoneNumberDetailed: type: object example: id: '1293384261075731499' record_type: phone_number phone_number: '+19705555098' country_iso_alpha2: US status: active tags: - tag_1 - tag_2 external_pin: '1234' connection_id: '1293384261075731499' connection_name: connection-name customer_reference: customer-reference messaging_profile_id: abc85f64-5717-4562-b3fc-2c9600000000 messaging_profile_name: regional-customers billing_group_id: 86f58db9-0fe3-4adc-9d1f-46e66e6e9323 emergency_enabled: true emergency_address_id: '1315261609962112019' emergency_status: active call_forwarding_enabled: true cnam_listing_enabled: true caller_id_name_enabled: true call_recording_enabled: true t38_fax_gateway_enabled: true phone_number_type: local inbound_call_screening: disabled purchased_at: '2019-10-23T18:10:00.000Z' created_at: '2019-10-23T18:10:00.000Z' updated_at: '2019-10-24T18:10:00.000Z' hd_voice_enabled: true source_type: number_order deletion_lock_enabled: false properties: id: $ref: '#/components/schemas/numbers_IntId' record_type: type: string example: phone_number description: Identifies the type of the resource. readOnly: true phone_number: type: string description: The +E.164-formatted phone number associated with this record. readOnly: true country_iso_alpha2: type: string description: The ISO 3166-1 alpha-2 country code of the phone number. example: US readOnly: true status: type: string description: The phone number's current status. enum: - purchase-pending - purchase-failed - port-pending - port-failed - active - deleted - emergency-only - ported-out - port-out-pending - requirement-info-pending - requirement-info-under-review - requirement-info-exception - provision-pending readOnly: true tags: type: array description: A list of user-assigned tags to help manage the phone number. items: type: string external_pin: type: - string - 'null' description: >- If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism. connection_name: type: - string - 'null' description: >- The user-assigned name of the connection to be associated with this phone number. readOnly: true connection_id: type: - string - 'null' description: Identifies the connection associated with the phone number. customer_reference: type: - string - 'null' description: A customer reference string for customer look ups. example: MY REF 001 messaging_profile_id: type: - string - 'null' description: Identifies the messaging profile associated with the phone number. messaging_profile_name: type: - string - 'null' description: The name of the messaging profile associated with the phone number. example: regional-customers billing_group_id: type: - string - 'null' description: Identifies the billing group associated with the phone number. emergency_enabled: type: boolean description: Indicates whether emergency services are enabled for this number. readOnly: true emergency_address_id: type: - string - 'null' description: Identifies the emergency address associated with the phone number. readOnly: true emergency_status: type: string description: >- Indicates the status of the provisioning of emergency services for the phone number. This field contains information about activity that may be ongoing for a number where it either is being provisioned or deprovisioned but is not yet enabled/disabled. enum: - active - deprovisioning - disabled - provisioning - provisioning-failed call_forwarding_enabled: type: boolean default: true description: >- Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints. readOnly: true cnam_listing_enabled: type: boolean description: Indicates whether a CNAM listing is enabled for this number. readOnly: true caller_id_name_enabled: type: boolean description: Indicates whether caller ID is enabled for this number. readOnly: true call_recording_enabled: type: boolean description: Indicates whether call recording is enabled for this number. readOnly: true t38_fax_gateway_enabled: type: boolean description: Indicates whether T38 Fax Gateway for inbound calls to this number. readOnly: true purchased_at: type: string description: ISO 8601 formatted date indicating when the resource was purchased. readOnly: true created_at: type: string description: ISO 8601 formatted date indicating when the resource was created. readOnly: true format: date-time phone_number_type: type: string description: >- The phone number's type. Note: For numbers purchased prior to July 2023 or when fetching a number's details immediately after a purchase completes, the legacy values `tollfree`, `shortcode` or `longcode` may be returned instead. enum: - local - toll_free - mobile - national - shared_cost - landline - tollfree - shortcode - longcode readOnly: true inbound_call_screening: type: string enum: - disabled - reject_calls - flag_calls default: disabled description: >- The inbound_call_screening setting is a phone number configuration option variable that allows users to configure their settings to block or flag fraudulent calls. It can be set to disabled, reject_calls, or flag_calls. This feature has an additional per-number monthly cost associated with it. updated_at: type: string description: ISO 8601 formatted date indicating when the resource was updated. readOnly: true hd_voice_enabled: type: boolean description: Indicates whether HD voice is enabled for this number. readOnly: true source_type: description: >- Indicates if the phone number was purchased or ported in. For some numbers this information may not be available. anyOf: - type: string enum: - number_order - port_request - type: 'null' readOnly: true deletion_lock_enabled: type: boolean description: >- Indicates whether deletion lock is enabled for this number. When enabled, this prevents the phone number from being deleted via the API or Telnyx portal. required: - id - record_type - phone_number - country_iso_alpha2 - status - tags - external_pin - created_at - phone_number_type - purchased_at - deletion_lock_enabled PaginationMeta: type: object properties: total_pages: type: integer example: 3 total_results: type: integer example: 55 page_number: type: integer example: 2 page_size: type: integer example: 25 numbers_Error: properties: code: type: string example: '10007' title: type: string example: Unexpected error detail: type: string example: An unexpected error occured. source: type: object properties: pointer: description: JSON pointer (RFC6901) to the offending entity. type: string example: /base parameter: description: Indicates which query parameter caused the error. type: string meta: type: object properties: url: type: string description: URL with additional information on the error. example: https://developers.telnyx.com/docs/overview/errors/10015 type: object numbers_Errors: properties: errors: type: array items: $ref: '#/components/schemas/numbers_Error' type: object numbers_IntId: type: string description: Identifies the resource. example: '1293384261075731499' readOnly: true securitySchemes: bearerAuth: scheme: bearer type: http ````