--- title: "List phone numbers" method: GET path: "/api/relay/rest/phone_numbers" tags: ["Phone Numbers"] --- # List phone numbers `GET /api/relay/rest/phone_numbers` Returns a list of your Phone Numbers. The phone numbers are returned sorted by creation date, with the most recent phone numbers appearing first. The list is filterable by sending in any of the following parameters. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). ## Query parameters - `filter_name` string - `filter_number` string - `page_number` integer - `page_size` integer - `page_token` string ## Response `200` The request has succeeded. - PhoneNumberListResponse — Response containing a list of phone numbers. - `links` PaginationLinks, required — Pagination links for list responses. - `self` string, required — Link to the current page. - `first` string, required — Link to the first page. - `next` string — Link to the next page. Only present when there are more results. - `prev` string — Link to the previous page. Only present when not on the first page. - `data` PhoneNumber[], required — List of phone numbers. - `id` string, uuid, required — Universal Unique Identifier. - `number` string, required — The phone number in E.164 format. - `name` string, nullable, required — The name given to the phone number. Helps to distinguish different phone numbers within your project. - `capabilities` PhoneNumberCapability[], required — A list of communication methods this phone number supports. - `number_type` 'toll-free' | 'longcode', required — Phone number type. - `e911_address_id` string, uuid, required — Universal Unique Identifier. - `e911_status` 'pending' | 'active' | 'failed' | 'pending_removal' | 'unregistered', required — E911 provisioning status of a phone number. - `created_at` string, date-time, required — The date the number was added to your project. - `updated_at` string, date-time, required — The date the number was last updated. - `next_billed_at` string, date-time, nullable, required — The next date the number will be billed for. - `call_handler` 'relay_context' | 'relay_topic' | 'relay_script' | 'relay_application' | 'relay_connector' | 'relay_sip_endpoint' | 'relay_verto_endpoint' | 'laml_webhooks' | 'laml_application' | 'dialogflow' | 'video_room' | 'call_flow' | 'ai_agent' | 'fabric_subscriber' | 'sip_gateway' | 'call_queue', required — Call handler type for phone numbers. - `calling_handler_resource_id` string, uuid, required — Universal Unique Identifier. - `call_receive_mode` 'voice' | 'fax', required — Call receive mode. - `call_request_url` string, nullable, required — The URL to make a request to when using the laml_webhooks call handler. - `call_request_method` 'GET' | 'POST', required — HTTP method type. - `call_fallback_url` string, nullable, required — The fallback URL to make a request to when using the laml_webhooks call handler and the call_request_url fails. - `call_fallback_method` 'GET' | 'POST', required — HTTP method type. - `call_status_callback_url` string, nullable, required — The URL to make status callbacks to when using the laml_webhooks call handler. - `call_status_callback_method` 'GET' | 'POST', required — HTTP method type. - `call_laml_application_id` string, nullable, required — The ID of the LaML Application to use when using the laml_application call handler. - `call_dialogflow_agent_id` string, nullable, required — The ID of the Dialogflow Agent to start when using the dialogflow call handler. - `call_relay_topic` string, nullable, required — A string representing the Relay topic to forward incoming calls to. This is only used (and required) when call_handler is set to relay_topic. - `call_relay_topic_status_callback_url` string, nullable, required — A string representing a URL to send status change messages to. This is only used (and required) when call_handler is set to relay_topic. - `call_relay_script_url` string, nullable, required — The URL to make a request to when using the relay_script call handler. The URL must respond with a valid SWML script. - `call_relay_context` string, nullable, required — The name of the Relay Context to send this call to when using the relay_context call handler. - `call_relay_context_status_callback_url` string, nullable, required — A string representing a URL to send status change messages to. This is only used (and required) when call_handler is set to relay_context. - `call_relay_application` string, nullable, required — The name of the Relay Application to send this call to when using the relay_application call handler. - `call_relay_connector_id` string, nullable, required — The ID of the Relay Connector to send this call to when using the relay_connector call handler. - `call_sip_endpoint_id` string, uuid, required — Universal Unique Identifier. - `call_verto_resource` string, nullable, required — The name of the Verto Relay Endpoint to send this call to when using the relay_verto_endpoint call handler. - `call_video_room_id` string, uuid, required — Universal Unique Identifier. - `message_handler` 'relay_context' | 'relay_topic' | 'relay_application' | 'laml_webhooks' | 'laml_application', required — Message handler type for phone numbers. - `messaging_handler_resource_id` string, uuid, required — Universal Unique Identifier. - `message_request_url` string, nullable, required — The URL to make a request to when using the laml_webhooks message handler. - `message_request_method` 'GET' | 'POST', required — HTTP method type. - `message_fallback_url` string, nullable, required — The fallback URL to make a request to when using the laml_webhooks message handler and the message_request_url fails. - `message_fallback_method` 'GET' | 'POST', required — HTTP method type. - `message_laml_application_id` string, nullable, required — The ID of the LaML Application to use when using the laml_application message handler. - `message_relay_topic` string, nullable, required — The name of the Relay Topic to send this message to when using the relay_topic message handler. - `message_relay_context` string, nullable, required — The name of the Relay Context to send this message to when using the relay_context message handler. - `country_code` string, nullable, required — The ISO 3166-1 alpha-2 country code of the phone number. ## Other responses - `400` — The request is invalid. - `401` — Access is unauthorized. - `500` — An internal server error occurred. --- [API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/91fbe575ddf9/schema)