# List all Phone Numbers

GET https://YOUR_SPACE.signalwire.com/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).

Reference: https://signalwire.com/docs/apis/relay-rest/phone-numbers/list-phone-numbers

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: relay-rest
  version: 1.0.0
paths:
  /phone_numbers:
    get:
      operationId: list-phone-numbers
      summary: List all Phone Numbers
      description: >-
        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).
      tags:
        - subpackage_phoneNumbers
      parameters:
        - name: filter_name
          in: query
          description: >-
            The name given to the phone number. Will return all Phone Numbers
            containing this value as a substring.
          required: false
          schema:
            type: string
        - name: filter_number
          in: query
          description: >-
            The phone number in E164 format. Will return all Phone Numbers
            containing this value as a substring.
          required: false
          schema:
            type: string
        - name: page_number
          in: query
          description: The page number to retrieve (0-indexed).
          required: false
          schema:
            type: integer
            default: 0
        - name: page_size
          in: query
          description: The number of items per page (1-1000).
          required: false
          schema:
            type: integer
            default: 50
        - name: page_token
          in: query
          description: Token for cursor-based pagination. Required when page_number > 0.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            SignalWire Basic Authentication using Project ID and API Token.


            The client sends HTTP requests with the Authorization header
            containing

            the word Basic followed by a space and a base64-encoded string of
            project_id:token.

            The project ID will be used as the username and the API token as the
            password.


            Example:

            ```

            Authorization: Basic base64(project_id:token)

            ```
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberListResponse'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode400'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
servers:
  - url: https://YOUR_SPACE.signalwire.com/api/relay/rest
components:
  schemas:
    PaginationLinks:
      type: object
      properties:
        self:
          type: string
          description: Link to the current page.
        first:
          type: string
          description: Link to the first page.
        next:
          type: string
          description: Link to the next page. Only present when there are more results.
        prev:
          type: string
          description: Link to the previous page. Only present when not on the first page.
      required:
        - self
        - first
      description: Pagination links for list responses.
      title: PaginationLinks
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    PhoneNumberCapability:
      type: string
      enum:
        - voice
        - sms
        - mms
        - fax
      description: Phone number capability.
      title: PhoneNumberCapability
    PhoneNumberType:
      type: string
      enum:
        - toll-free
        - longcode
      description: Phone number type.
      title: PhoneNumberType
    PhoneNumberCallHandler:
      type: string
      enum:
        - 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
      description: Call handler type for phone numbers.
      title: PhoneNumberCallHandler
    CallReceiveMode:
      type: string
      enum:
        - voice
        - fax
      description: Call receive mode.
      title: CallReceiveMode
    HttpMethod:
      type: string
      enum:
        - GET
        - POST
      description: HTTP method type.
      title: HttpMethod
    PhoneNumberMessageHandler:
      type: string
      enum:
        - relay_context
        - relay_topic
        - relay_application
        - laml_webhooks
        - laml_application
      description: Message handler type for phone numbers.
      title: PhoneNumberMessageHandler
    PhoneNumber:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifier of the phone number.
        number:
          type: string
          description: The phone number in E.164 format.
        name:
          type:
            - string
            - 'null'
          description: >-
            The name given to the phone number. Helps to distinguish different
            phone numbers within your project.
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumberCapability'
          description: A list of communication methods this phone number supports.
        number_type:
          $ref: '#/components/schemas/PhoneNumberType'
          description: The type of number this is defined as.
        e911_address_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The E911 address ID associated with this phone number.
        created_at:
          type: string
          format: date-time
          description: The date the number was added to your project.
        updated_at:
          type: string
          format: date-time
          description: The date the number was last updated.
        next_billed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The next date the number will be billed for.
        call_handler:
          oneOf:
            - $ref: '#/components/schemas/PhoneNumberCallHandler'
            - type: 'null'
          description: What type of handler you want to run on inbound calls.
        calling_handler_resource_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The unique identifier of the calling handler resource.
        call_receive_mode:
          $ref: '#/components/schemas/CallReceiveMode'
          description: How do you want to receive the incoming call.
        call_request_url:
          type:
            - string
            - 'null'
          description: >-
            The URL to make a request to when using the laml_webhooks call
            handler.
        call_request_method:
          oneOf:
            - $ref: '#/components/schemas/HttpMethod'
            - type: 'null'
          description: >-
            The HTTP method to use when making a request to the
            call_request_url.
        call_fallback_url:
          type:
            - string
            - 'null'
          description: >-
            The fallback URL to make a request to when using the laml_webhooks
            call handler and the call_request_url fails.
        call_fallback_method:
          oneOf:
            - $ref: '#/components/schemas/HttpMethod'
            - type: 'null'
          description: >-
            The HTTP method to use when making a request to the
            call_fallback_url.
        call_status_callback_url:
          type:
            - string
            - 'null'
          description: >-
            The URL to make status callbacks to when using the laml_webhooks
            call handler.
        call_status_callback_method:
          oneOf:
            - $ref: '#/components/schemas/HttpMethod'
            - type: 'null'
          description: >-
            The HTTP method to use when making a request to the
            call_status_callback_url.
        call_laml_application_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the LaML Application to use when using the
            laml_application call handler.
        call_dialogflow_agent_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the Dialogflow Agent to start when using the dialogflow
            call handler.
        call_relay_topic:
          type:
            - string
            - 'null'
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            The name of the Relay Context to send this call to when using the
            relay_context call handler.
        call_relay_context_status_callback_url:
          type:
            - string
            - 'null'
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            The name of the Relay Application to send this call to when using
            the relay_application call handler.
        call_relay_connector_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the Relay Connector to send this call to when using the
            relay_connector call handler.
        call_sip_endpoint_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: >-
            The ID of the Relay SIP Endpoint to send this call to when using the
            relay_sip_endpoint call handler.
        call_verto_resource:
          type:
            - string
            - 'null'
          description: >-
            The name of the Verto Relay Endpoint to send this call to when using
            the relay_verto_endpoint call handler.
        call_video_room_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: >-
            The ID of the Video Room to send this call to when using the
            video_room call handler.
        message_handler:
          oneOf:
            - $ref: '#/components/schemas/PhoneNumberMessageHandler'
            - type: 'null'
          description: What type of handler you want to run on inbound messages.
        messaging_handler_resource_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The unique identifier of the messaging handler resource.
        message_request_url:
          type:
            - string
            - 'null'
          description: >-
            The URL to make a request to when using the laml_webhooks message
            handler.
        message_request_method:
          oneOf:
            - $ref: '#/components/schemas/HttpMethod'
            - type: 'null'
          description: >-
            The HTTP method to use when making a request to the
            message_request_url.
        message_fallback_url:
          type:
            - string
            - 'null'
          description: >-
            The fallback URL to make a request to when using the laml_webhooks
            message handler and the message_request_url fails.
        message_fallback_method:
          oneOf:
            - $ref: '#/components/schemas/HttpMethod'
            - type: 'null'
          description: >-
            The HTTP method to use when making a request to the
            message_fallback_url.
        message_laml_application_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the LaML Application to use when using the
            laml_application message handler.
        message_relay_topic:
          type:
            - string
            - 'null'
          description: >-
            The name of the Relay Topic to send this message to when using the
            relay_topic message handler.
        message_relay_context:
          type:
            - string
            - 'null'
          description: >-
            The name of the Relay Context to send this message to when using the
            relay_context message handler.
        country_code:
          type:
            - string
            - 'null'
          description: The ISO 3166-1 alpha-2 country code of the phone number.
      required:
        - id
        - number
        - name
        - capabilities
        - number_type
        - e911_address_id
        - created_at
        - updated_at
        - next_billed_at
        - call_handler
        - calling_handler_resource_id
        - call_receive_mode
        - call_request_url
        - call_request_method
        - call_fallback_url
        - call_fallback_method
        - call_status_callback_url
        - call_status_callback_method
        - call_laml_application_id
        - call_dialogflow_agent_id
        - call_relay_topic
        - call_relay_topic_status_callback_url
        - call_relay_script_url
        - call_relay_context
        - call_relay_context_status_callback_url
        - call_relay_application
        - call_relay_connector_id
        - call_sip_endpoint_id
        - call_verto_resource
        - call_video_room_id
        - message_handler
        - messaging_handler_resource_id
        - message_request_url
        - message_request_method
        - message_fallback_url
        - message_fallback_method
        - message_laml_application_id
        - message_relay_topic
        - message_relay_context
        - country_code
      description: Phone number model.
      title: PhoneNumber
    PhoneNumberListResponse:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/PaginationLinks'
          description: Pagination links.
        data:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: List of phone numbers.
      required:
        - links
        - data
      description: Response containing a list of phone numbers.
      title: PhoneNumberListResponse
    TypesStatusCodesStatusCode400Error:
      type: string
      enum:
        - Bad Request
      title: TypesStatusCodesStatusCode400Error
    Types.StatusCodes.StatusCode400:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode400Error'
      required:
        - error
      description: The request is invalid.
      title: Types.StatusCodes.StatusCode400
    TypesStatusCodesStatusCode401Error:
      type: string
      enum:
        - Unauthorized
      title: TypesStatusCodesStatusCode401Error
    Types.StatusCodes.StatusCode401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error'
      required:
        - error
      description: Access is unauthorized.
      title: Types.StatusCodes.StatusCode401
    TypesStatusCodesStatusCode500Error:
      type: string
      enum:
        - Internal Server Error
      title: TypesStatusCodesStatusCode500Error
    Types.StatusCodes.StatusCode500:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error'
      required:
        - error
      description: An internal server error occurred.
      title: Types.StatusCodes.StatusCode500
  securitySchemes:
    SignalWireBasicAuth:
      type: http
      scheme: basic
      description: >-
        SignalWire Basic Authentication using Project ID and API Token.


        The client sends HTTP requests with the Authorization header containing

        the word Basic followed by a space and a base64-encoded string of
        project_id:token.

        The project ID will be used as the username and the API token as the
        password.


        Example:

        ```

        Authorization: Basic base64(project_id:token)

        ```

```

## SDK Code Examples

```python
import requests

url = "https://your_space.signalwire.com/api/relay/rest/phone_numbers"

headers = {"Authorization": "Basic <project_id>:<api_token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://your_space.signalwire.com/api/relay/rest/phone_numbers';
const options = {method: 'GET', headers: {Authorization: 'Basic <project_id>:<api_token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://your_space.signalwire.com/api/relay/rest/phone_numbers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Basic <project_id>:<api_token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://your_space.signalwire.com/api/relay/rest/phone_numbers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <project_id>:<api_token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://your_space.signalwire.com/api/relay/rest/phone_numbers")
  .header("Authorization", "Basic <project_id>:<api_token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://your_space.signalwire.com/api/relay/rest/phone_numbers', [
  'headers' => [
    'Authorization' => 'Basic <project_id>:<api_token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://your_space.signalwire.com/api/relay/rest/phone_numbers");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic <project_id>:<api_token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Basic <project_id>:<api_token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://your_space.signalwire.com/api/relay/rest/phone_numbers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```