Navbar
Logo icon Name
  • Relay
  • Client SDKs & Libraries
  • REST API Reference
  • Resources
  • REST API Reference

    Introduction

    Welcome to SignalWire's Relay REST API. Relay is the next generation of interactive communication APIs available at SignalWire, and the REST API is a set of endpoints that make interacting with Relay, simple and familiar.

    The Relay REST API is structured like most other REST APIs: we use predictable and clear resource-oriented URLs that utilize built in HTTP features like authentication, verbs and error codes. This enables you to easily use any HTTP client in any language to make requests.

    Proper HTTP status codes and JSON are returned in all REST API endpoints, including errors.

    Be sure to subscribe to the SignalWire Community for information on new features and changes to the API and language libraries.

    Base URL

    Each space on SignalWire gets its own subdomain and each space will have its own URLs for accessing the Relay REST API.

    All calls in the provided examples use the following as the base URL:

    https://your-space.signalwire.com/api/relay/rest
    

    However, please note that the actual base URL you will use will differ for each space, since it will be customized to include your unique space name. For your own custom URL, replace your-space with your unique subdomain.

    Authentication

    Example Authenticated Request

        curl https://your-space.signalwire.com/api/relay/rest/sip_endpoints \
          -u 'YourProjectID:YourAuthToken'
    
    

    curl uses the -u option to pass in HTTP Basic Auth credentials to the request. You can find your Project ID and Auth Tokens from your SignalWire Dashboard.

    Most Relay REST API endpoints require authentication using HTTP Basic Auth. HTTP Basic Authentication requires you to send an Authorization header of your Project ID and Authentication Token. This should be supported in almost all HTTP clients.

    Each project has its own Project ID and Authentication Tokens you will need to use when making each request to the API. You can find your Project ID and Authentication Tokens in your SignalWire Dashboard.

    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

    Errors

    SignalWire uses the conventional HTTP response codes to indicate whether the request was successful.

    In general:

    • codes in the 2xx range mean the request was successful
    • codes in the 4xx range mean an error occurred with your request and will contain an error message explaining what was wrong with the request
    • codes in the 5xx range indicates an error with SignalWire's servers (a rare occurrence!).

    Data Formats

    Dates and Times

    All dates and times in requests to and from SignalWire Relay API are UTC, and presented in ISO 8601 format.

    For example, the date and time of 8:01 AM CDT on July 23rd, 2018 is presented as: 2018-07-23T13:01:00Z

    Phone Numbers

    All phone numbers in requests to or from the SignalWire Relay REST API are in E.164 format, an unambiguous general format for specifying international phone numbers. Numbers in this format start with a plus sign ("+") and the country code.

    For example, a US-based phone number like (555) 123-4567 would be formatted like: +15551234567.

    If a number cannot be represented in E.164 format, then SignalWire uses the raw Caller ID string that was received.

    Client Libraries and SDKs

    Coming Soon

    Pagination

    An example of the paging information returned for all index routes.

    {
      "links": {
        "self": "/api/relay/rest/example_url_to_the_current_page",
        "first": "/api/relay/rest/example_url_to_the_first_page",
        "next": "/api/relay/rest/example_url_to_the_next_page",
        "prev": "/api/relay/rest/example_url_to_the_prev_page"
      },
      "data" : [
        { ... },
        { ... }
      ]
    }
    

    Most top-level API resources support bulk fetching via a list or index method. These list endpoints share a common structure to make handling lists, filtering and pagination easier to work with.

    All list endpoints will return partial "pages" of results. These results will also contain meta information about how to get the next page of results, or the previous one, or return to the start.

    It is highly recommended to use the link values to navigate your list results. This will ensure your properly page through all of resources and your result set is not affected by new resources being created, or paging scheme changing.

    Resources

    Addresses

    Addresses allow you to keep a collection of addresses which can be used for things like E911 (Enhanced 911) or phone number locality requirements for certain countries around the world.

    The Address object

    Example response of a Address

    {
      "id": "f512b541-4df5-46da-9f9d-cb5f21c555bb",
      "label": "My Address",
      "country": "US",
      "first_name": "Emmett",
      "last_name": "Brown",
      "street_number": "1640",
      "street_name": "Riverside Drive",
      "city": "Hill Valley",
      "state": "CA",
      "postal_code": "91905"
      }
    
    Attribute
    id string The unique identifier of the Address on SignalWire. This can be used to show or delete the address programatically.
    label string A friendly name given to the address to help distinguish and search for different addresses within your project.
    country string The ISO 3166 Alpha 2 country code.
    first_name string First name of the occupant associated with this address.
    last_name string Last name of the occupant associated with this address.
    street_number string The number portion of the street address.
    street_name string The name portion of the street address.
    address_type string Optional If the address is divided into multiple sub-addresses, such as an apartment or office building, this identifies how the address is divided. If the address is a single occupant address, address_type may be omitted.
    address_number string Optional If the address is divided into multiple sub-addresses, such as an apartment or office building, this identifies the particular sub-address. If the address is a single occupant address, address_number may be omitted.
    city string The city portion of the street address.
    state string The state/province/region of the street address.
    postal_code string The postal code of the street address.

    Create an Address

    POST /addresses

    curl https://your-space.signalwire.com/api/relay/rest/addresses \
      -X POST
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{
        "label": "Work Address",
        "first_name": "Carl G.",
        "last_name": "Busch",
        "street_number": "2630",
        "street_name": "Hegal Place",
        "address_type": "Apartment",
        "address_number": "42",
        "city": "Alexandria",
        "state": "VA",
        "postal_code": "23242",
        "country": "US"
      }'
    

    Response 201 CREATED

    {
      "id": "6b6e4f90-5d8d-4f19-9a48-3f460f61d579",
      "label": "Work Address",
      "first_name": "Carl G.",
      "last_name": "Busch",
      "street_number": "2630",
      "street_name": "Hegal Place",
      "address_type": "Apartment",
      "address_number": "42",
      "city": "Alexandria",
      "state": "VA",
      "postal_code": "23242",
      "country": "US"
      }
    

    To create a new Address, make a POST request to the Address resource.

    Parameter
    label required A friendly name given to the address to help distinguish and search for different addresses within your project.
    first_name required First name of the occupant associated with this address.
    last_name required Last name of the occupant associated with this address.
    street_number required The number portion of the street address.
    street_name required The name portion of the street address.
    city required The city portion of the street address.
    state required The state/province/region of the street address. In the USA and Canada, use the two-letter abbreviated form, such as CA for California.
    postal_code required The postal code of the street address.
    country required The ISO 3166 Alpha 2 country code.
    address_type optional If the address is divided into multiple sub-addresses, such as an apartment or office building, this identifies how the address is divided. If the address is a single occupant address, address_type may be omitted. Possible values are: Apartment, Basement, Building, Department, Floor, Office, Penthouse, Suite, Trailer, Unit
    address_number optional If the address is divided into multiple sub-addresses, such as an apartment or office building, this identifies the particular sub-address. If the address is a single occupant address, address_number may be omitted.

    Retrieve an Address

    GET /addresses/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/addresses/6b6e4f90-5d8d-4f19-9a48-3f460f61d579 \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "id": "6b6e4f90-5d8d-4f19-9a48-3f460f61d579",
      "label": "Work Address",
      "first_name": "Carl G.",
      "last_name": "Busch",
      "street_number": "2630",
      "street_name": "Hegal Place",
      "address_type": "Apartment",
      "address_number": "42",
      "city": "Alexandria",
      "state": "VA",
      "postal_code": "23242",
      "country": "US"
      }
    

    Retrieves the details of an Address that has been previously created. Use the unique ID that was returned from your previous request to identify the specific instance.

    Parameter
    None

    Delete an Address

    DELETE /addresses/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/addresses/6b6e4f90-5d8d-4f19-9a48-3f460f61d579 \
      -X DELETE \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Removes an Address for your account's active addresses but the address will continue to be associated with any numbers it was applied to. For example, if an address is associated as the E911 address of a phone number and the address is then deleted from your project, it will stay associated as the E911 address for that number.

    Parameter
    None

    List all Addresses

    GET /addresses

    curl https://your-space.signalwire.com/api/relay/rest/addresses \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/number_groups?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/number_groups?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/number_groups?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/number_groups?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "id": "f512b541-4df5-46da-9f9d-cb5f21c555bb",
          "label": "My Address",
          "country": "US",
          "first_name": "Emmett",
          "last_name": "Brown",
          "street_number": "1640",
          "street_name": "Riverside Drive",
          "city": "Hill Valley",
          "state": "CA",
          "postal_code": "91905"
          },
        {...},
        {...}
      ]
    }
    

    Returns a list of your Addresses. The addresses are returned sorted by creation date, with the most recent appearing first.

    Domain Applications

    This is an object that represents a Domain Application within your project. A Domain Application is a custom DNS hostname associated to your project that can accept SIP traffic and take programmatic actions. If anyone makes a SIP request to your domain, SignalWire will use the configured handler to provide instructions on how to handle the incoming call.

    The Domain Application object

    Example response of a domain application object.

    {
      "id": "9a7b70bd-adfd-4121-a5d1-72211729e1a4",
      "type": "domain_application",
      "name": "Test App",
      "identifier": "test_id",
      "domain": "your-space-test_id",
      "ip_auth_enabled": true,
      "ip_auth": [
        "1.2.3.4",
        "5.6.7.8"
      ],
      "call_handler": "relay_context",
      "call_request_url": null,
      "call_request_method": "POST",
      "call_fallback_url": null,
      "call_fallback_method": "POST",
      "call_status_callback_url": null,
      "call_status_callback_method": "POST",
      "call_relay_context": "incoming",
      "call_laml_application_id": null,
      "encryption": "required",
      "codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "VP8",
        "H264"
      ],
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ]
    }
    
    
    Attribute
    id string The unique identifier of the domain application on SignalWire. This can be used to update or delete the application programatically.
    type string A string representation of the type of object this record is.
    name string A string representing the friendly name for this domain application.
    identifier string A string representing the identifier portion of the domain application. Must be unique across your project.
    domain string A string representation of the subdomain for this application.
    ip_auth_enabled boolean Whether the domain application will enforce IP authentication for incoming requests.
    ip_auth array A list containing whitelisted IP addresses and IP blocks used if ip_auth_enabled is true.
    call_handler string A string representing how this domain application handles calls. Valid values are relay_context, laml_webhooks, and laml_application.
    call_request_url string A string representing the LaML URL to access when a call is received. This is only used when call_handler is set to laml_webhooks.
    call_request_method string A string representing the HTTP method to use with call_request_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_fallback_url string A string representing the LaML URL to access when the call to call_request_url fails. This is only used when call_handler is set to laml_webhooks.
    call_fallback_method string A string representing the HTTP method to use with call_fallback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_url string A string representing a URL to send status change messages to. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_method string A string representing the HTTP method to use with call_status_callback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_relay_context string A string representing the Relay context to forward incoming calls to. This is only used when call_handler is set to relay_context.
    call_laml_application_id string A string representing the ID of the LaML application to forward incoming calls to. This is only used when call_handler is set to laml_application.
    encryption string A string representing whether connections to this domain application require encryption or if encryption is optional. Encryption will always be used if possible. Valid values are optional and required.
    codecs required A list of codecs this domain application will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, and H264.
    ciphers required A list of encryption ciphers this domain application will support.

    Currently supported values are: AEAD_AES_256_GCM_8, AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, and AES_CM_128_HMAC_SHA1_32.

    Create a Domain Application

    POST /domain_applications

    curl https://your-space.signalwire.com/api/relay/rest/domain_applications \
      -X POST \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Test App",
        "identifier": "test_id",
        "call_handler": "relay_context",
        "call_relay_context": "incoming",
        "ip_auth_enabled": true,
        "ip_auth": ["8.8.8.8", "4.4.4.4"],
        "encryption": "required",
        "codecs": ["PCMU", "PCMA"],
        "ciphers": ["AEAD_AES_256_GCM_8"]
      }'
    

    Response 201 CREATED

    {
      "type": "domain_application",
      "id": "fc1961e6-0a98-475f-8e33-eb24794f9eed",
      "name": "Test App",
      "domain": "your-space-test_id",
      "identifier": "test_id",
      "ip_auth_enabled": true,
      "ip_auth": [
        "1.2.3.4",
        "5.6.7.8"
      ],
      "call_handler": "relay_context",
      "call_request_url": null,
      "call_request_method": "POST",
      "call_fallback_url": null,
      "call_fallback_method": "POST",
      "call_status_callback_url": null,
      "call_status_callback_method": "POST",
      "call_relay_context": "incoming",
      "call_laml_application_id": null,
      "encryption": "required",
      "codecs": [
        "PCMU",
        "PCMA"
      ],
      "ciphers": [
        "AEAD_AES_256_GCM_8"
      ]
    }
    

    To create a new domain application, you send a POST request to the domain application resource.

    Parameter
    name required A string representing the friendly name for this domain application.
    identifier required A string representing the identifier portion of the domain application. Must be unique across your project.
    ip_auth_enabled boolean Whether the domain application will enforce IP authentication for incoming requests.
    ip_auth array A list containing whitelisted IP addresses and IP blocks used if ip_auth_enabled is true.
    call_handler required A string representing how this domain application handles calls. Valid values are relay_context, laml_webhooks, and laml_application.
    call_request_url required*if call_handler is set to laml_webhooks A string representing the LaML URL to access when a call is received. This is only used when call_handler is set to laml_webhooks.
    call_request_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_request_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_fallback_url required*if call_handler is set to laml_webhooks A string representing the LaML URL to access when the call to call_request_url fails. This is only used when call_handler is set to laml_webhooks.
    call_fallback_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_fallback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_url required*if call_handler is set to laml_webhooks A string representing a URL to send status change messages to. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_status_callback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_relay_context required*if call_handler is set to relay_context A string representing the Relay context to forward incoming calls to. This is only used when call_handler is set to relay_context.
    call_laml_application_id required*if call_handler is set to laml_application A string representing the ID of the LaML application to forward incoming calls to. This is only used when call_handler is set to laml_application.
    encryption required A string representing whether connections to this domain application require encryption or if encryption is optional. Encryption will always be used if possible. Valid values are optional and required.
    codecs required A list of codecs this domain application will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, and H264.

    At least one value must be supplied.
    ciphers required A list of encryption ciphers this domain application will support.

    Currently supported values are: AEAD_AES_256_GCM_8, AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, and AES_CM_128_HMAC_SHA1_32.

    At least one value must be supplied.

    Retrieve a Domain Application

    GET /domain_applications/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/domain_applications/3df3ab89-3e86-4cc3-88cd-c0c8415bccca \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "type": "domain_application",
      "id": "3df3ab89-3e86-4cc3-88cd-c0c8415bccca",
      "name": "Test",
      "domain": "your-space-test",
      "identifier": "test",
      "ip_auth_enabled": false,
      "ip_auth": [],
      "call_handler": "laml_application",
      "call_request_url": "",
      "call_request_method": "POST",
      "call_fallback_url": "",
      "call_fallback_method": "POST",
      "call_status_callback_url": "",
      "call_status_callback_method": "POST",
      "call_relay_context": "",
      "call_laml_application_id": "85f70cf6-92e2-4b46-892d-e726e233a45a",
      "encryption": "default",
      "codecs": [
        "PCMU",
        "PCMA"
      ],
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ]
    }
    
    

    Retrieves the details of a domain application that has been previously created. Use the unique ID that was returned from your previous request to identify the specific domain application.

    Parameter
    None

    Update a Domain Application

    PUT /domain_applications

    curl https://your-space.signalwire.com/api/relay/rest/domain_applications/95d6b094-d3fd-4617-b98c-ab156857a1fe \
      -X PUT \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "New Name",
        "ip_auth": [ "1.1.1.1" ]
      }'
    '
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/domain_applications?page_number=0&page_size=50",
        "first": "/api/relay/rest/domain_applications?page_size=50"
      },
      "data": [
        {
          "type": "domain_application",
          "id": "95d6b094-d3fd-4617-b98c-ab156857a1fe",
          "name": "New Name",
          "domain": "your-space-test_id",
          "identifier": "test_id",
          "ip_auth_enabled": true,
          "ip_auth": [
            "1.1.1.1"
          ],
          "call_handler": "relay_context",
          "call_request_url": null,
          "call_request_method": "POST",
          "call_fallback_url": null,
          "call_fallback_method": "POST",
          "call_status_callback_url": null,
          "call_status_callback_method": "POST",
          "call_relay_context": "incoming",
          "call_laml_application_id": null,
          "encryption": "default",
          "codecs": [
            "PCMU",
            "PCMA"
          ],
          "ciphers": [
            "AEAD_AES_256_GCM_8"
          ]
        }
      ]
    }
    

    Updates the specific domain application by setting the values of any parameters passed in. Any parameters not provided will be unchanged.

    Parameter
    name required A string representing the friendly name for this domain application.
    identifier required A string representing the identifier portion of the application. Must be unique across your project.
    ip_auth_enabled boolean Whether the domain application will enforce IP authentication for incoming requests.
    ip_auth array A list containing whitelisted IP addresses and IP blocks used if ip_auth_enabled is true.
    call_handler required A string representing how this domain application handles calls. Valid values are relay_context, laml_webhooks, and laml_application.
    call_request_url required*if call_handler is set to laml_webhooks A string representing the LaML URL to access when a call is received. This is only used when call_handler is set to laml_webhooks.
    call_request_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_request_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_fallback_url required*if call_handler is set to laml_webhooks A string representing the LaML URL to access when the call to call_request_url fails. This is only used when call_handler is set to laml_webhooks.
    call_fallback_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_fallback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_url required*if call_handler is set to laml_webhooks A string representing a URL to send status change messages to. This is only used when call_handler is set to laml_webhooks.
    call_status_callback_method required*if call_handler is set to laml_webhooks A string representing the HTTP method to use with call_status_callback_url. Valid values are GET and POST. This is only used when call_handler is set to laml_webhooks.
    call_relay_context required*if call_handler is set to relay_context A string representing the Relay context to forward incoming calls to. This is only used when call_handler is set to relay_context.
    call_laml_application_id required*if call_handler is set to laml_application A string representing the ID of the LaML application to forward incoming calls to. This is only used when call_handler is set to laml_application.
    encryption required A string representing whether connections to this domain application require encryption or if encryption is optional. Encryption will always be used if possible. Valid values are optional and required.
    codecs required A list of codecs this domain application will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, and H264.

    At least one value must be supplied.
    ciphers required A list of encryption ciphers this domain application will support.

    Currently supported values are: AEAD_AES_256_GCM_8, AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, and AES_CM_128_HMAC_SHA1_32.

    At least one value must be supplied.

    Delete a Domain Application

    DELETE /domain_applications/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/domain_applications/67075301-69b2-4fc3-8a2c-c95a69a5665e \
      -X DELETE \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Permanently deletes a domain application. It cannot be undone. Will reject any audio or video from currently registered devices and deregister any connections.

    Parameter
    None

    List all Domain Applications

    GET /domain_applications

    curl https://your-space.signalwire.com/api/relay/rest/domain_applications \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/domain_applications?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/domain_applications?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/domain_applications?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/domain_applications?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "type": "domain_application",
          "id": "95d6b094-d3fd-4617-b98c-ab156857a1fe",
          "name": "New Name",
          "domain": "your-space-test_id",
          "identifier": "test_id",
          "ip_auth_enabled": true,
          "ip_auth": [
            "1.1.1.1"
          ],
          "call_handler": "relay_context",
          "call_request_url": null,
          "call_request_method": "POST",
          "call_fallback_url": null,
          "call_fallback_method": "POST",
          "call_status_callback_url": null,
          "call_status_callback_method": "POST",
          "call_relay_context": "incoming",
          "call_laml_application_id": null,
          "encryption": "default",
          "codecs": [
            "PCMU",
            "PCMA"
          ],
          "ciphers": [
            "AEAD_AES_256_GCM_8"
          ]
        },
        {...},
        {...}
      ]
    }
    

    Returns a list of your domain applications. The domain applications are returned sorted by creation date, with the most recent domain applications appearing first. The list is filterable by sending in any of the following parameters.

    Parameter
    filter_domain optional String representing the domain portion of the domain application. Will return all domain applications containing this value as a substring.
    filter_name optional String representing the name portion of the domain application. Will return all domain applications containing this value as a substring.

    Number Groups

    This is an object that represents a Number Group within your project. Number Groups allow you to build collections of Phone Numbers to be used for things like outbound message pools, white/black-lists, and much more.

    The Number Group object

    Example response of a Number Group object

    {
      "id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "name": "My Number Group",
      "phone_number_count": 4
    }
    
    Attribute
    id string The unique identifier of the Number Group on SignalWire. This can be used to update or delete the group programatically.
    name string The name given to the number group. Helps to distinguish different groups within your project.
    phone_number_count integer The number of phone numbers within the group.
    sticky_sender boolean Whether this number group uses the same 'From' number for outbound requests to a number, or chooses a random one.

    Create a Number Group

    POST /number_groups

    curl https://your-space.signalwire.com/api/relay/rest/number_groups \
      -X POST \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{ "name" : "My Number Group" }'
    

    Response 201 CREATED

    {
      "id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "name": "My Number Group",
      "phone_number_count": 0,
      "sticky_sender": false
    }
    

    To create a new Number Group, you send a POST request to the Number Group resource.

    Parameter
    name required The name given to the number group to distinguish different groups within your project.
    sticky_sender optional Whether the number group uses the same 'From' number for outbound requests to a number, or chooses a random one. Defaults to false.

    Retrieve a Number Group

    GET /number_groups/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "name": "My Number Group",
      "phone_number_count": 0,
      "sticky_sender": false
    }
    

    Retrieves the details of a Number Group that has been previously created. Use the unique ID that was returned from your previous request to identify the specific Number Group.

    Parameter
    None

    Update a Number Group

    PUT /number_groups

    curl https://your-space.signalwire.com/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe \
      -X PUT \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{ "name" : "My Updated Number Group" }'
    

    Response 200 OK

    {
      "id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "name": "My Updated Number Group",
      "phone_number_count": 0,
      "sticky_sender": false
    }
    

    Updates the specific Number Group by setting the values of any parameters passed in. Any parameters not provided will be unchanged.

    Parameter
    name required The name given to the number group to distinguish different groups within your project.

    Delete a Number Group

    DELETE /number_groups/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe \
      -X DELETE \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Permanently deletes a Number Group. This cannot be undone. This action will not release Phone Numbers, it will just disassociate them from the Number Group.

    Parameter
    None

    List all Number Groups

    GET /number_groups

    curl https://your-space.signalwire.com/api/relay/rest/number_groups \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/number_groups?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/number_groups?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/number_groups?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/number_groups?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
          "name": "My Updated Number Group",
          "phone_number_count": 0,
          "sticky_sender": false
        },
        {...},
        {...}
      ]
    }
    

    Returns a list of your Number Groups. The groups are returned sorted by creation date, with the most recent appearing first. The list is filterable by sending in any of the following parameters.

    Parameter
    filter_name optional The name given to the number group to distinguish different groups within your project. Will return all SIP Endpoints containing this value as a substring.

    Number Group Membership

    This is an object that represents a Phone Number in a Number Group within your project. Number Groups allow you to build collections of Phone Numbers, Number Group Memberships represent a single Phone Number's association to a Number Group.

    The Number Group Membership object

    Example response of a Number Group Membership object

    {
      "id": "c4b14f1b-1da7-4275-bdf7-4950738f2c30",
      "number_group_id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "phone_number": {
        "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
        "name": "Jenny",
        "number": "+15558675309",
        "capabilities": [ "voice", "sms", "mms", "fax" ]
      }
    }
    
    Attribute
    id string The unique identifier of the Number Group Membership on SignalWire. This can be used to delete the membership programatically.
    number_group_id string The unique identifier of the Number Group this membership is associated with.
    phone_number object A representation of the phone number this membership is associated with.

    Create a Number Group Membership

    POST /number_groups/{NumberGroupID}/number_group_memberships

    curl https://your-space.signalwire.com/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships \
      -X POST \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{ "phone_number_id" : "fce723d3-6018-488c-a126-fbcd05bcc670" }'
    

    Response 201 CREATED

    {
      "id": "c4b14f1b-1da7-4275-bdf7-4950738f2c30",
      "number_group_id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "phone_number": {
        "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
        "name": "Jenny",
        "number": "+15558675309",
        "capabilities": [ "voice", "sms", "mms", "fax" ]
      }
    }
    

    To create a new Number Group Membership, you send a POST request to the Number Group Membership resource.

    Parameter
    phone_number_id required The unique identifier of the Phone Number you would like to add to the Number Group.

    Retrieve a Number Group Membership

    GET /number_group_memberships/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/number_group_memberships/c4b14f1b-1da7-4275-bdf7-4950738f2c30 \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "id": "c4b14f1b-1da7-4275-bdf7-4950738f2c30",
      "number_group_id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
      "phone_number": {
        "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
        "name": "Jenny",
        "number": "+15558675309",
        "capabilities": [ "voice", "sms", "mms", "fax" ]
      }
    }
    

    Retrieves the details of a Number Group Membership that has been previously created. Use the unique ID that was returned from your previous request to identify the specific Number Group Membership.

    Parameter
    None

    Delete a Number Group

    DELETE /number_group_memberships/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/number_group_memberships/c4b14f1b-1da7-4275-bdf7-4950738f2c30 \
      -X DELETE \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Permanently deletes a Number Group Membership. This cannot be undone. This action will not release Phone Numbers, it will just disassociate the Phone Number from the Number Group.

    Parameter
    None

    List all Number Group Memberships

    GET /number_groups/{NumberGroupID}/number_group_memberships

    curl https://your-space.signalwire.com/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/number_groups/0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe/number_group_memberships?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "id": "c4b14f1b-1da7-4275-bdf7-4950738f2c30",
          "number_group_id": "0bd099b3-ae67-4769-8b5e-f3ffbdb2f3fe",
          "phone_number": {
            "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
            "name": "Jenny",
            "number": "+15558675309",
            "capabilities": [ "voice", "sms", "mms", "fax" ]
          }
        },
        {...},
        {...}
      ]
    }
    

    Returns a list of a Number Group's Memberships. The memberships are returned sorted by creation date, with the most recent appearing first.

    Phone Numbers

    This is an object that represents a Phone Number within your project.

    The Phone Number object

    Example response of a Phone Number object

    {
      "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
      "name": "Jenny",
      "number": "+15558675309",
      "capabilities": [ "voice", "sms", "mms", "fax" ],
      "number_type": "toll-free",
      "e911_address_id": null,
      "created_at": "2019-04-10T18:04:57Z",
      "updated_at": "2019-04-10T18:04:57Z",
      "next_billed_at": "2019-05-01T00:00:00Z",
      "call_handler": "relay_context",
      "call_receive_mode": "voice",
      "call_request_url": "",
      "call_request_method": "POST",
      "call_fallback_url": "",
      "call_fallback_method": "POST",
      "call_status_callback_url": "",
      "call_status_callback_method": "POST",
      "call_laml_application_id": null,
      "call_dialogflow_agent_id": null,
      "call_relay_context": "my_relay_app",
      "call_relay_connector_id": null,
      "call_sip_endpoint_id": null,
      "call_verto_resource": "",
      "message_handler": "relay_context",
      "message_request_url": "",
      "message_request_method": "POST",
      "message_fallback_url": "",
      "message_fallback_method": "POST",
      "message_laml_application_id": null,
      "message_relay_context": "my_relay_app"
    }
    
    Attribute
    id string The unique identifier of the Phone Number on SignalWire. This can be used to find, update or delete the phone number programatically.
    name string The name given to the phone number. Helps to distinguish different phone numbers within your project.
    number string The phone number in E164 format.
    capabilities string A list of communication methods this phone number supports. Possible values are: voice, fax, sms, mms.
    number_type string The type of number this is defined as. Possible values are: toll-free or longcode.
    e911_address_id string A list of communication methods this phone number supports.
    created_at datetime The date the number was added to your project.
    updated_at datetime The date the number was last updated.
    next_billed_at datetime The next date the number will be billed for.
    call_handler string What type of handler you want to run on inbound calls. Possible values are: relay_context, laml_webhooks, laml_application, dialogflow, relay_connector, relay_sip_endpoint, relay_verto_endpoint.
    call_receive_mode string How do you want to receive the incoming call. Possible values are: voice or fax. Default is voice.
    call_request_url string The URL to make a request to when using the laml_webhooks call handler.
    call_request_method string The HTTP method to use when making a request to the call_request_url. Possible values are: POST or GET. Default is POST.
    call_fallback_url string The fallback URL to make a request to when using the laml_webhooks call handler and the call_request_url fails.
    call_fallback_method string The HTTP method to use when making a request to the call_fallback_url. Possible values are: POST or GET. Default is POST.
    call_status_callback_url string The URL to make status callbacks to when using the laml_webhooks call handler.
    call_status_callback_method string The HTTP method to use when making a request to the call_status_callback_url. Possible values are: POST or GET. Default is POST.
    call_laml_application_id string The ID of the LaML Application to use when using the laml_application call handler.
    call_dialogflow_agent_id string The ID of the Dialogflow Agent to start when using the dialogflow call handler.
    call_relay_context string The name of the Relay Context to send this call to when using the relay_context call handler.
    call_relay_connector_id string The ID of the Relay Connector to send this call to when using the relay_connector call handler.
    call_sip_endpoint_id string The ID of the Relay SIP Endpoint to send this call to when using the relay_sip_endpoint call handler.
    call_verto_resource string The name of the Verto Relay Endpoint to send this call to when using the relay_verto_endpoint call handler.
    message_handler string What type of handler you want to run on inbound messages. Possible values are: relay_context, laml_webhooks, laml_application.
    message_request_url string The URL to make a request to when using the laml_webhooks message handler.
    message_request_method string The HTTP method to use when making a request to the message_request_url. Possible values are: POST or GET. Default is POST.
    message_fallback_url string The fallback URL to make a request to when using the laml_webhooks message handler and the message_request_url fails.
    message_fallback_method string The HTTP method to use when making a request to the message_fallback_url. Possible values are: POST or GET. Default is POST.
    message_laml_application_id string The ID of the LaML Application to use when using the laml_application message handler.
    message_relay_context string The name of the Relay Context to send this message to when using the relay_context message handler.

    List all Phone Numbers

    GET /phone_numbers

    curl https://your-space.signalwire.com/api/relay/rest/phone_numbers \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/phone_numbers?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/phone_numbers?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/phone_numbers?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/phone_numbers?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
          "name": "Jenny",
          "number": "+15558675309",
          "capabilities": [ "voice", "sms", "mms", "fax" ],
          "number_type": "toll-free",
          "e911_address_id": null,
          "created_at": "2019-04-10T18:04:57Z",
          "updated_at": "2019-04-10T18:04:57Z",
          "next_billed_at": "2019-05-01T00:00:00Z",
          "call_handler": "relay_context",
          "call_receive_mode": "voice",
          "call_request_url": "",
          "call_request_method": "POST",
          "call_fallback_url": "",
          "call_fallback_method": "POST",
          "call_status_callback_url": "",
          "call_status_callback_method": "POST",
          "call_laml_application_id": null,
          "call_dialogflow_agent_id": null,
          "call_relay_context": "my_relay_app",
          "call_relay_connector_id": null,
          "call_sip_endpoint_id": null,
          "call_verto_resource": "",
          "message_handler": "relay_context",
          "message_request_url": "",
          "message_request_method": "POST",
          "message_fallback_url": "",
          "message_fallback_method": "POST",
          "message_laml_application_id": null,
          "message_relay_context": "my_relay_app"
        },
        {...},
        {...}
      ]
    }
    

    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.

    Parameter
    filter[name] optional The name given to the phone number. Will return all Phone Numbers containing this value as a substring.
    filter[number] optional The phone number in E164 format. Will return all Phone Numbers containing this value as a substring.

    Retrieve a Phone Number

    GET /phone_numbers/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/phone_numbers/fce723d3-6018-488c-a126-fbcd05bcc670 \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
      "name": "Jenny",
      "number": "+15558675309",
      "capabilities": [ "voice", "sms", "mms", "fax" ],
      "number_type": "toll-free",
      "e911_address_id": null,
      "created_at": "2019-04-10T18:04:57Z",
      "updated_at": "2019-04-10T18:04:57Z",
      "next_billed_at": "2019-05-01T00:00:00Z",
      "call_handler": "relay_context",
      "call_receive_mode": "voice",
      "call_request_url": "",
      "call_request_method": "POST",
      "call_fallback_url": "",
      "call_fallback_method": "POST",
      "call_status_callback_url": "",
      "call_status_callback_method": "POST",
      "call_laml_application_id": null,
      "call_dialogflow_agent_id": null,
      "call_relay_context": "my_relay_app",
      "call_relay_connector_id": null,
      "call_sip_endpoint_id": null,
      "call_verto_resource": "",
      "message_handler": "relay_context",
      "message_request_url": "",
      "message_request_method": "POST",
      "message_fallback_url": "",
      "message_fallback_method": "POST",
      "message_laml_application_id": null,
      "message_relay_context": "my_relay_app"
    }
    

    Retrieves the details of a Phone Number that has been previously created.

    Parameter
    None

    Update a Phone Number

    PUT /phone_numbers/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/phone_numbers/fce723d3-6018-488c-a126-fbcd05bcc670 \
      -X PUT \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{ "name" : "My Updated Phone Number" }'
    

    Response 200 OK

    {
      "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
      "name": "My Updated Phone Number",
      "number": "+15558675309",
      "capabilities": [ "voice", "sms", "mms", "fax" ],
      "number_type": "toll-free",
      "e911_address_id": null,
      "created_at": "2019-04-10T18:04:57Z",
      "updated_at": "2019-04-10T18:04:57Z",
      "next_billed_at": "2019-05-01T00:00:00Z",
      "call_handler": "relay_context",
      "call_receive_mode": "voice",
      "call_request_url": "",
      "call_request_method": "POST",
      "call_fallback_url": "",
      "call_fallback_method": "POST",
      "call_status_callback_url": "",
      "call_status_callback_method": "POST",
      "call_laml_application_id": null,
      "call_dialogflow_agent_id": null,
      "call_relay_context": "my_relay_app",
      "call_relay_connector_id": null,
      "call_sip_endpoint_id": null,
      "call_verto_resource": "",
      "message_handler": "relay_context",
      "message_request_url": "",
      "message_request_method": "POST",
      "message_fallback_url": "",
      "message_fallback_method": "POST",
      "message_laml_application_id": null,
      "message_relay_context": "my_relay_app"
    }
    

    Updates the specific Phone Number by setting the values of any parameters passed in. Any parameters not provided will be unchanged.

    Parameter
    name optional The name given to the phone number. Helps to distinguish different phone numbers within your project.
    call_handler optional What type of handler you want to run on inbound calls. Possible values are: relay_context, laml_webhooks, laml_application, dialogflow, relay_connector, relay_sip_endpoint, relay_verto_endpoint. Default is laml_webhooks.
    message_handler optional What type of handler you want to run on inbound messages. Possible values are: relay_context, laml_webhooks, laml_application. Default is laml_webhooks.

    Depending on which call or message handler you choose to use, different parameters can be used:

    Call Handler relay_context:

    call_relay_context required The name of the Relay Context to send this call to.

     

    Call Handler laml_webhooks:

    call_receive_mode optional How do you want to receive the incoming call. Possible values are: voice or fax. Default is voice.
    call_request_url optional The URL to make a request to.
    call_request_method optional The HTTP method to use when making a request to the call_request_url. Possible values are: POST or GET. Default is POST.
    call_fallback_url optional The fallback URL to make a request to when the call_request_url fails.
    call_fallback_method optional The HTTP method to use when making a request to the call_fallback_url. Possible values are: POST or GET. Default is POST.
    call_status_callback_url optional The URL to make status callbacks to.
    call_status_callback_method optional The HTTP method to use when making a request to the call_status_callback_url. Possible values are: POST or GET. Default is POST.

     

    Call Handler laml_application:

    call_receive_mode optional How do you want to receive the incoming call. Possible values are: voice or fax. Default is voice.
    call_laml_application_id required The ID of the LaML Application to use.

     

    Call Handler dialogflow:

    call_dialogflow_agent_id required The ID of the Dialogflow Agent to start.

     

    Call Handler relay_connector:

    call_relay_connector_id required The ID of the Relay Connector to send this call to.

     

    Call Handler relay_sip_endpoint:

    call_sip_endpoint_id required The ID of the Relay SIP Endpoint to send this call to.

     

    Call Handler relay_verto_endpoint:

    call_verto_resource required The name of the Verto Relay Endpoint to send this call to.

     

    Message Handler relay_context:

    message_relay_context required The name of the Relay Context to send this message to.

     

    Message Handler laml_webhooks:

    message_request_url optional The URL to make a request to.
    message_request_method optional The HTTP method to use when making a request to the message_request_url. Possible values are: POST or GET. Default is POST.
    message_fallback_url optional The fallback URL to make a request to when the message_request_url fails.
    message_fallback_method optional The HTTP method to use when making a request to the message_fallback_url. Possible values are: POST or GET. Default is POST.

     

    Message Handler laml_application:

    message_laml_application_id required The ID of the LaML Application to use.

    Search for available Phone Numbers to Purchase

    GET /phone_numbers/search

    curl https://your-space.signalwire.com/api/relay/rest/phone_numbers/search \
      -G \
      -d 'areacode=553' \
      -d 'contains=123' \
      -u 'YourProjectID:YourAuthToken' \
    

    Response 200 OK

    {
        "links": {}, // Reserved for future use
        "data": [
            {
                "e164": "+15554390116",
                "national_number_formatted": "(555) 439-0116",
                "international_number_formatted": "+1 555-439-0116",
                "region": "NC",
                "rate_center": "RALEIGH",
                "country_code": "US"
            },
            {...},
            {...}
        ]
    }
    

    Returns a list of phone numbers available for purchase that match the given search criteria parameters.

    Parameter
    areacode optional An areacode to search within.
    number_type optional Search for either local or toll-free numbers. Defaults to local.
    starts_with optional A string of 3 to 7 digits that should be used as the start of a number. Cannot be used in combination with contains or ends_with.
    contains optional A string of 3 to 7 digits that should appear somewhere in the number. Cannot be used in combination with starts_with or ends_with.
    ends_with optional A string of 3 to 7 digits that should be used as the end of a number. Cannot be used in combination with starts_with or contains.
    max_results optional The maximum number of matches to return. Upper limit of 100. Defaults to 50.
    region optional A region or state to search within. Must be an ISO 3166-2 alpha-2 code, i.e. TX for Texas. Cannot be used in combination with areacode.
    city optional A specific City to search within. Must be used in combination with region. Cannot be used in combination with areacode, starts_with, contains, or ends_with.

    Purchase a Phone Number

    POST /phone_numbers

    curl https://your-space.signalwire.com/api/relay/rest/phone_numbers/ \
      -X POST \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken' \
      -d '{ "number" : "+15554390116" }'
    

    Response 200 OK

    {
      "id": "fce723d3-6018-488c-a126-fbcd05bcc670",
      "name": "",
      "number": "+15558675309",
      "capabilities": [ "voice", "sms", "mms", "fax" ],
      "number_type": "toll-free",
      "e911_address_id": null,
      "created_at": "2019-04-10T18:04:57Z",
      "updated_at": "2019-04-10T18:04:57Z",
      "next_billed_at": "2019-05-01T00:00:00Z",
      "call_handler": "relay_context",
      "call_receive_mode": "voice",
      "call_request_url": "",
      "call_request_method": "POST",
      "call_fallback_url": "",
      "call_fallback_method": "POST",
      "call_status_callback_url": "",
      "call_status_callback_method": "POST",
      "call_laml_application_id": null,
      "call_dialogflow_agent_id": null,
      "call_relay_context": "my_relay_app",
      "call_relay_connector_id": null,
      "call_sip_endpoint_id": null,
      "call_verto_resource": "",
      "message_handler": "relay_context",
      "message_request_url": "",
      "message_request_method": "POST",
      "message_fallback_url": "",
      "message_fallback_method": "POST",
      "message_laml_application_id": null,
      "message_relay_context": "my_relay_app"
    }
    

    Purchase a number and add it to your project.

    Parameter
    number required The E164 number you wish to purchase and create.
    Attribute
    id string The unique identifier of the Phone Number on SignalWire. This can be used to find, update or delete the phone number programatically.
    name string The name given to the phone number. Helps to distinguish different phone numbers within your project.
    number string The phone number in E164 format.
    capabilities string A list of communication methods this phone number supports. Possible values are: voice, fax, sms, mms.
    number_type string The type of number this is defined as. Possible values are: toll-free or longcode.
    e911_address_id string A list of communication methods this phone number supports.
    created_at datetime The date the number was added to your project.
    updated_at datetime The date the number was last updated.
    next_billed_at datetime The next date the number will be billed for.
    call_handler string What type of handler you want to run on inbound calls. Possible values are: relay_context, laml_webhooks, laml_application, dialogflow, relay_connector, relay_sip_endpoint, relay_verto_endpoint.
    call_receive_mode string How do you want to receive the incoming call. Possible values are: voice or fax. Default is voice.
    call_request_url string The URL to make a request to when using the laml_webhooks call handler.
    call_request_method string The HTTP method to use when making a request to the call_request_url. Possible values are: POST or GET. Default is POST.
    call_fallback_url string The fallback URL to make a request to when using the laml_webhooks call handler and the call_request_url fails.
    call_fallback_method string The HTTP method to use when making a request to the call_fallback_url. Possible values are: POST or GET. Default is POST.
    call_status_callback_url string The URL to make status callbacks to when using the laml_webhooks call handler.
    call_status_callback_method string The HTTP method to use when making a request to the call_status_callback_url. Possible values are: POST or GET. Default is POST.
    call_laml_application_id string The ID of the LaML Application to use when using the laml_application call handler.
    call_dialogflow_agent_id string The ID of the Dialogflow Agent to start when using the dialogflow call handler.
    call_relay_context string The name of the Relay Context to send this call to when using the relay_context call handler.
    call_relay_connector_id string The ID of the Relay Connector to send this call to when using the relay_connector call handler.
    call_sip_endpoint_id string The ID of the Relay SIP Endpoint to send this call to when using the relay_sip_endpoint call handler.
    call_verto_resource string The name of the Verto Relay Endpoint to send this call to when using the relay_verto_endpoint call handler.
    message_handler string What type of handler you want to run on inbound messages. Possible values are: relay_context, laml_webhooks, laml_application.
    message_request_url string The URL to make a request to when using the laml_webhooks message handler.
    message_request_method string The HTTP method to use when making a request to the message_request_url. Possible values are: POST or GET. Default is POST.
    message_fallback_url string The fallback URL to make a request to when using the laml_webhooks message handler and the message_request_url fails.
    message_fallback_method string The HTTP method to use when making a request to the message_fallback_url. Possible values are: POST or GET. Default is POST.
    message_laml_application_id string The ID of the LaML Application to use when using the laml_application message handler.
    message_relay_context string The name of the Relay Context to send this message to when using the relay_context message handler.

    Phone Number Lookup

    This endpoint allows you to look up validity and formatting information about a number. You can optionally lookup additional information about the number such as carrier and caller ID data.

    GET /lookup/phone_number/{e164_number}?include=carrier,cnam

    curl https://your-space.signalwire.com/api/relay/rest/lookup/phone_number/+15551234567?include=carrier,cnam \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    
    Parameter
    include optional Further number information to include in the response, some of which are billable.

    You can specify:
    carrier : Lookup full carrier information for the number.
    cnam : Lookup Caller ID information for the number.

    Separate multiple values with a comma: include=carrier,cnam.

    Base Request

    GET /lookup/phone_number/{e164_number}

    curl https://your-space.signalwire.com/api/relay/rest/lookup/phone_number/+15551234567 \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    

    Response 200 OK

    {
      "country_code_number": "1",
      "national_number": "5551234567",
      "possible_number": true,
      "valid_number": true,
      "national_number_formatted": "(555) 123-4567",
      "international_number_formatted": "+1 555-123-4567",
      "e164": "+15551234567",
      "location": "Texas",
      "country_code": "US",
      "timezones": [
        "America/Austin"
      ],
      "number_type": "Fixed Line or Mobile"
    }
    

    The base request returns validation and formatting information about the number. It will attempt to identify the country code, and location in addition to the type of number. This information is based on the number format as published by each country. For more detailed information, see include carrier details request example.

    Attribute
    country_code_number string The Country code associated with the number
    national_number string Number in the countries national format.
    possible_number boolean Whether the number supplied is a possible number. For example, in the United States +15551234567 is a possible number, but it is not a valid number.
    valid_number boolean Whether the number supplied is a valid number.
    national_number_formatted string The E164 number formatted in national format.
    international_number_formatted string The E164 number formatted in international format.
    e164 string The number in E164 format.
    location string The location of the number based on its area code and NPA.
    country_code string The ISO3166 alpha 2 country code associated with the number
    timezones string The time zones associated with the number
    number_type string The type of number based on its area code and NPA. For more detailed record of number type, see include carrier details request

    Include Carrier Details

    GET /lookup/phone_number/{e164_number}?include=carrier

    curl https://your-space.signalwire.com/api/relay/rest/lookup/phone_number/+15551234567?include=carrier \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    

    Response 200 OK

    {
      "country_code_number": "1",
      "national_number": "5551234567",
      "possible_number": true,
      "valid_number": true,
      "national_number_formatted": "(555) 123-4567",
      "international_number_formatted": "+1 555-123-4567",
      "e164": "+15551234567",
      "location": "Texas",
      "country_code": "US",
      "timezones": [
        "America/Austin"
      ],
      "number_type": "Fixed Line or Mobile",
      "carrier": {
        "lrn": "15551234567",
        "spid": "683X",
        "ocn": "12345",
        "lata": "99999",
        "city": "Aberdeen",
        "state": "WA",
        "jurisdiction": "indeterminate",
        "lec": "Verizon",
        "linetype": "landline"
      },
    }
    

    Adding include=carrier to your request will do a live lookup to determine the current carrier information about this number. This includes more accurate information about what type of number as well as location.

    Only valid for numbers with a +1 country code.

    Attributes
    lrn string The LRN associated with the number
    spid string The Service Profile Identifier associated with the number
    ocn string The Operating Company Number associated with the number
    city string The City associated with the number
    state string The State/Province/Region associated with the number
    lec string The LEC or Carrier of the number.
    lata string The Local Access and Transport Area number associated with the number
    jurisdiction string The Jurisdiction associated with the number
    line_type string The type of line the number is. Generally either wireless or landline

    Include CNAM Details

    GET /lookup/phone_number/{e164_number}?include=cnam

    curl https://your-space.signalwire.com/api/relay/rest/lookup/phone_number/+15551234567?include=cnam \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    

    Response 200 OK

    {
      "country_code_number": "1",
      "national_number": "5551234567",
      "possible_number": true,
      "valid_number": true,
      "national_number_formatted": "(555) 123-4567",
      "international_number_formatted": "+1 555-123-4567",
      "e164": "+15551234567",
      "location": "Texas",
      "country_code": "US",
      "timezones": [
        "America/Austin"
      ],
      "number_type": "Fixed Line or Mobile",
      "cnam": {
        "caller_id": "John Smith",
      }
    }
    

    Adding include=cnam to your request will do a live lookup to determine the current caller ID information about this number.

    Only valid for numbers with a +1 country code.

    Attributes
    caller_id string The caller ID associated with the number.

    SIP Endpoints

    This is an object that represents a SIP endpoint within your project. You can connect external softphones or other SIP enabled devices to an endpoint and send or receive audio and video.

    The SIP Endpoint object

    Example response of a SIP Endpoint object

    {
      "id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
      "username": "c3p0",
      "caller_id": "C-3P0",
      "send_as": "random",
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "VP8",
        "H264"
      ],
      "encryption": "required",
      "type": "sip_endpoint"
    }
    
    Attribute
    id string The unique identifier of the SIP Endpoint on SignalWire. This can be used to update or delete the endpoint programatically.
    username string String representing the username portion of the endpoint. Must be unique across your project.
    caller_id string Friendly Caller ID used as the CNAM when dialing a phone number or the From when dialing another SIP Endpoint.
    send_as string When dialing a PSTN phone number, you must send it From a number you have purchased or verified. send_as indicates which number this endpoint has set as its origination. random indicates it will randomly choose a purchased or verified number from within the project.
    ciphers array A list of encryption ciphers this endpoint will support.
    codecs array A list of codecs this endpoint will support.
    encryption string A string representing whether connections to this endpoint require encryption or if encryption is optional. Encryption will always be used if possible.
    type string A string representation of the type of object this record is.

    Create a SIP Endpoint

    POST /endpoints/sip

    curl https://your-space.signalwire.com/api/relay/rest/endpoints/sip \
      -X POST \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "username" : "c3p0",
        "password" : "yavinOrBust",
        "caller_id" : "C-3P0"
      }'
    

    Response 201 CREATED

    {
      "id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
      "username": "c3p0",
      "caller_id": "C-3P0",
      "send_as": "random",
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "VP8",
        "H264"
      ],
      "encryption": "optional",
      "type": "sip_endpoint"
    }
    

    To create a new SIP Endpoint, you send a POST request to the SIP Endpoint resource.

    Parameter
    username required String representing the username portion of the endpoint. Must be unique across your project and must not container white space characters or @.
    password required A password to authenticate registrations to this endpoint.
    caller_id optional Friendly Caller ID used as the CNAM when dialing a phone number or the From when dialing another SIP Endpoint.
    send_as optional The e164 formatted number you which to set as the originating number when dialing PSTN phone numbers from this SIP Endpoint.

    Defaults to the project's SIP Settings default send as number.
    ciphers optional A list of encryption ciphers this endpoint will support.

    Currently supported values are: AEAD_AES_256_GCM_8,AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, AES_CM_128_HMAC_SHA1_32.

    Defaults to the project's SIP Settings default cipher list.
    codecs optional A list of codecs this endpoint will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, H264.

    Defaults to the project's SIP Settings default codec list.
    encryption optional A string representing whether connections to this endpoint require encryption or if encryption is optional. Encryption will always be used if possible.

    Possible values are default, required, optional.

    Defaults to the project's SIP Settings default.

    Retrieve a SIP Endpoint

    GET /endpoints/sip/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/endpoints/sip/67075301-69b2-4fc3-8a2c-c95a69a5665e \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
      "username": "c3p0",
      "caller_id": "C-3P0",
      "send_as": "random",
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "VP8",
        "H264"
      ],
      "encryption": "optional",
      "type": "sip_endpoint"
    }
    

    Retrieves the details of a SIP Endpoint that has been previously created. Use the unique ID that was returned from your previous request to identify the specific SIP Endpoint.

    Parameter
    None

    Update a SIP Endpoint

    PUT /endpoints/sip

    curl https://your-space.signalwire.com/api/relay/rest/endpoints/sip/67075301-69b2-4fc3-8a2c-c95a69a5665e \
      -X PUT \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "password" : "HothIsTheNewYavin",
        "codecs" : ["OPUS"],
        "send_as" : "+15551234567"
      }'
    

    Response 200 OK

    {
      "id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
      "username": "c3p0",
      "caller_id": "C-3P0",
      "send_as": "+15551234567",
      "ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "codecs": ["OPUS"],
      "encryption": "optional",
      "type": "sip_endpoint"
    }
    

    Updates the specific SIP Endpoint by setting the values of any parameters passed in. Any parameters not provided will be unchanged.

    Parameter
    username optional String representing the username portion of the endpoint. Must be unique across your project and must not container white space characters or @.
    password optional A password to authenticate registrations to this endpoint.
    caller_id optional Friendly Caller ID used as the CNAM when dialing a phone number or the From when dialing another SIP Endpoint.
    send_as optional The e164 formatted number you which to set as the originating number when dialing PSTN phone numbers from this SIP Endpoint.

    Defaults to the project's SIP Settings default send as number.
    ciphers optional A list of encryption ciphers this endpoint will support.

    Currently supported values are: AEAD_AES_256_GCM_8,AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, AES_CM_128_HMAC_SHA1_32. You can unset the custom cipher list and use the project's SIP Settings default cipher list by sending an empty array.

    Defaults to the project's SIP Settings default cipher list.
    codecs optional A list of codecs this endpoint will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, H264. You can unset the custom codec list and use the project's SIP Settings default codec list by sending an empty array.

    Defaults to the project's SIP Settings default codec list.
    encryption optional A string representing whether connections to this endpoint require encryption or if encryption is optional. Encryption will always be used if possible.

    Possible values are default, required, optional.

    Defaults to the project's SIP Settings default.

    Delete a SIP Endpoint

    DELETE /endpoints/sip/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/endpoints/sip/67075301-69b2-4fc3-8a2c-c95a69a5665e \
      -X DELETE \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Permanently deletes a SIP Endpoint. It cannot be undone. Will reject any audio or video from currently registered devices and deregister any connections.

    Parameter
    None

    List all SIP Endpoints

    GET /endpoints/sip

    curl https://your-space.signalwire.com/api/relay/rest/endpoints/sip \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/endpoints/sip?page[limit]=50&page[number]=2",
        "first": "/api/relay/rest/endpoints/sip?page[limit]=50&page[number]=1",
        "next": "/api/relay/rest/endpoints/sip?page[limit]=50&page[number]=3",
        "prev": "/api/relay/rest/endpoints/sip?page[limit]=50&page[number]=1"
      },
      "data" : [
        {
          "id": "67075301-69b2-4fc3-8a2c-c95a69a5665e",
          "username": "c3p0",
          "caller_id": "C-3P0",
          "send_as": "+15551234567",
          "ciphers": [
            "AEAD_AES_256_GCM_8",
            "AES_256_CM_HMAC_SHA1_80",
            "AES_CM_128_HMAC_SHA1_80",
            "AES_256_CM_HMAC_SHA1_32",
            "AES_CM_128_HMAC_SHA1_32"
          ],
          "codecs": [
            "OPUS",
            "G722",
            "PCMU",
            "PCMA",
            "VP8",
            "H264"
          ],
          "encryption": "optional",
          "type": "sip_endpoint"
        },
        {...},
        {...}
      ]
    }
    

    Returns a list of your SIP Endpoints. The endpoints are returned sorted by creation date, with the most recent endpoints appearing first. The list is filterable by sending in any of the following parameters.

    Parameter
    filter_username optional String representing the username portion of the endpoint. Will return all SIP Endpoints containing this value as a substring.
    filter_caller_id optional Friendly Caller ID used as the CNAM when dialing a phone number or the From when dialing another SIP Endpoint. Will return all SIP Endpoints containing this value as a substring.

    SIP Profile

    This is an object that represents a SIP profile within your project, allowing you to specify the host and default settings for SIP Endpoints.

    The SIP Profile object

    Example response of a SIP Profile object

    {
      "domain": "your-space-example.sip.signalwire.com",
      "domain_identifier": "example",
      "default_codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "G729",
        "VP8",
        "H264"
      ],
      "default_ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "default_encryption": "optional",
      "default_send_as": "random"
    }
    
    Attribute
    domain string A string representation of the fully qualified domain name for this profile.
    domain_identifier string String representing the domain_identifier portion of the profile. Must be unique across your project.
    default_codecs array A list of codecs this profile will support.
    default_ciphers array A list of encryption ciphers this profile will support.
    default_encryption string A string representing whether connections to an endpoint that uses this profile require encryption or if encryption is optional. Encryption will always be used if possible.
    default_send_as string When dialing a PSTN phone number, you must send it From a number you have purchased or verified. default_send_as indicates which number this profile has set as its origination. random indicates it will randomly choose a purchased or verified number from within the project.

    Retrieve a SIP Profile

    GET /sip_profile

    curl https://your-space.signalwire.com/api/relay/rest/sip_profile \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "domain": "your-space-example.sip.signalwire.com",
      "domain_identifier": "example",
      "default_codecs": [
        "OPUS",
        "G722",
        "PCMU",
        "PCMA",
        "G729",
        "VP8",
        "H264"
      ],
      "default_ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "default_encryption": "optional",
      "default_send_as": "random"
    }
    

    Retrieves the details of a SIP Profile that has been previously created. Use the current project id that was set by authentication to identify the specific SIP Profile.

    Parameter
    None

    Update a SIP Endpoint

    PUT /sip_profile

    curl https://your-space.signalwire.com/api/relay/rest/sip_profile \
      -X PUT \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "default_codecs" : ["OPUS"],
        "default_send_as" : "+15551234567"
      }'
    

    Response 200 OK

    {
      "domain": "your-space-example.sip.signalwire.com",
      "domain_identifier": "example",
      "default_codecs": ["OPUS"],
      "default_ciphers": [
        "AEAD_AES_256_GCM_8",
        "AES_256_CM_HMAC_SHA1_80",
        "AES_CM_128_HMAC_SHA1_80",
        "AES_256_CM_HMAC_SHA1_32",
        "AES_CM_128_HMAC_SHA1_32"
      ],
      "default_encryption": "optional",
      "default_send_as": "+15551234567"
    }
    

    Updates the specific SIP Profile by setting the values of any parameters passed in. Any parameters not provided will be unchanged.

    Parameter
    domain_identifier string String representing the domain_identifier portion of the profile. Must be unique across your project.
    default_codecs array A list of codecs this profile will support.

    Currently supported values are: OPUS, G722, PCMU, PCMA, VP8, H264.
    default_ciphers array A list of encryption ciphers this profile will support.

    Currently supported values are: AEAD_AES_256_GCM_8,AES_256_CM_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_80, AES_256_CM_HMAC_SHA1_32, AES_CM_128_HMAC_SHA1_32.
    default_encryption string A string representing whether connections to an endpoint that uses this profile require encryption or if encryption is optional. Encryption will always be used if possible.

    Possible values are required or optional.
    default_send_as string The e164 formatted number you wish to set as the originating number when dialing PSTN phone numbers from a SIP Endpoint that uses this profile. Specify null or an empty string to randomly choose a purchased or verified number from within the project.

    Verified Caller IDs

    This is an object that represents a phone number that is not purchased through SignalWire. In order place a call from a phone number not purchased through SignalWire, you must first verify that you are the owner of that number. For more information on Verified Caller IDs you can read about them.

    How This Works

    In order to use a number that you have not purchased through SignalWire as a Caller ID, value you must first verifiy that you own that number. You are limited to 10 calls to a given number with a one week period.

    1. Create a Verified Caller ID Object.
    2. The SignalWire platform will place a call to the phone number that you specified.
    3. When the phone is answered, we will read a six-digit code.
    4. To verify that you are the owner, take that number and submit it to the Validate Verifications Endpoint.
      • You have 5 attempts to enter the code correctly.

    The Verified Caller ID Object

    
    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": false,
      "verified_at": null,
      "status": "Awaiting Verification"
    }
    
    Attribute
    type string The type of the returned object, this should be verified_caller_id.
    id string The unique identifier of the Verified Caller ID on SignalWire.
    name string String representing the name portion of the caller ID.
    extension string String representing the extension of the phone number for the caller ID. This is only used when placing the verification call.
    number string String representing the E.164 formatted phone number for the caller ID.
    verified boolean A boolean representing whether the number has been verified or not.
    verified_at string Nullable DateTime fields representing the date and time that the number was verified. If the number has not been verified, it will be null.
    status string String representing the verification status for the caller ID. Current values are "Verified" and "Awaiting Verification"

    Create a new Verified Caller ID

    POST /verified_caller_ids

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids \
      -X POST \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "C-3P0",
        "extension": "1234",
        "number": "+15551234567",
      }'
    

    Response 201 CREATED

    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": false,
      "verified_at": null,
      "status": "Awaiting Verification"
    }
    

    To send a verification call to a number, you send a POST request to the Verified Caller ID resource.

    Parameter
    number required String representing the phone number for the caller ID. This must be a valid, routeable phone number in E.164 format that is able to receive a voice phone call for verification.
    extension optional String representing an extension to dial after the phone number in the process of verification.
    name optional String representing the name for the phone number, if not provided the default will be the formatted number that has been provided.

    Retrieve a Verified Caller ID

    GET /verified_caller_ids/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids/3cfb912e-b200-4d09-aa91-7ffa849ea0f5 \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    

    Response 200 OK

    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": false,
      "verified_at": null,
      "status": "Awaiting Verification"
    }
    

    To retrieve an existing Verified Caller ID, you send a GET request to the Verified Caller ID resource. Use the unique ID that was returned from your previous request to identify the specific Verified Caller ID.

    Parameter
    None

    Update a Verified Caller ID

    PUT /verified_caller_ids/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids/3cfb912e-b200-4d09-aa91-7ffa849ea0f5 \
    -X PUT \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "C-3P0"
      }'
    

    Response 200 OK

    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": false,
      "verified_at": null,
      "status": "Awaiting Verification"
    }
    

    To update an existing Verified Caller ID, you send a `PUT request to the Verified Caller ID resource. Any parameters not passed in will remain unchanged.

    The extension is only used when sending a verification call, if you need to update the extension and initiate a new call - use the Create a Verified Caller ID endpoint.

    Parameter
    name optional String representing the name for the phone number, if not provided the default will be the formatted number that has been provided.

    Delete a Verified Caller ID

    DELETE /verified_caller_ids/{ID}

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids/67075301-69b2-4fc3-8a2c-c95a69a5665e \
      -X DELETE \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken'
    

    Response 204 No Content

    Permanently deletes a Verified Caller ID. You will no longer be able to place calls from this phone number.

    Parameter
    None

    List all Verified Caller IDs

    GET /verified_caller_ids

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids \
      -H 'Content-Type: application/json' \
      -u 'YourProjectID:YourAuthToken'
    

    Response 200 OK

    {
      "links": {
        "self": "/api/relay/rest/verified_caller_ids?page_size=50&page_number=2",
        "first": "/api/relay/rest/verified_caller_ids?page_size=50&page_number=1",
        "next": "/api/relay/rest/verified_caller_ids?page_size=50&page_number=3",
        "prev": "/api/relay/rest/verified_caller_ids?page_size=50&page_number=1"
      },
      "data" : [
        {
          "type": "verified_caller_id",
          "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
          "name": "C-3P0",
          "extension": "1234",
          "number": "+15551234567",
          "verified": false,
          "verified_at": null,
          "status": "Awaiting Verification"
        },
        {...},
        {...}
      ]
    }
    

    Returns a list of your Verified Caller IDs. The caller IDs are returned sorted by creation date, with the most recent caller IDs appearing first. The list is filterable by sending in any of the following parameters.

    Parameter
    filter_name optional String representing the name assigned to the caller ID. Will return all Verified Caller IDs containing this value as a substring.
    filter_number optional String representing the number assigned to the caller ID. Will return all Verified Caller IDs containing this value as a substring.

    Validate the Verification Code

    PUT /verified_caller_ids/{ID}/verification

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids/3cfb912e-b200-4d09-aa91-7ffa849ea0f5/verification \
    -X PUT \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json' \
      -d '{
        "verification_code": "123456"
      }'
    

    Response 200 OK

    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": true,
      "verified_at": "2020-03-19T07:22Z",
      "status": "Awaiting Verification"
    }
    

    Supplies the verification code that was read during the verification call.

    RESTRICTIONS

    • There is a limit of 5 attempts to enter a validation code for a number. Once exhausted, you may request a redial of the verification call to reset the code and try again.
    Parameter
    verification_code required String representing the verification code that was read during the verification call.

    Redial Verification Call

    POST /verified_caller_ids/{ID}/verification

    curl https://your-space.signalwire.com/api/relay/rest/verified_caller_ids/3cfb912e-b200-4d09-aa91-7ffa849ea0f5/verification \
    -X POST \
      -u 'YourProjectID:YourAuthToken' \
      -H 'Content-Type: application/json'
    

    Response 200 OK

    {
      "type": "verified_caller_id",
      "id": "3cfb912e-b200-4d09-aa91-7ffa849ea0f5",
      "name": "C-3P0",
      "extension": "1234",
      "number": "+15551234567",
      "verified": false,
      "verified_at": null,
      "status": "Awaiting Verification"
    }
    

    Places the verification call again, this will generate a new code to be read.

    RESTRICTIONS

    • You are limited to 10 redial verification calls to a given number with a one week period.
    • You must wait one minute before each redial verification call attempt.
    Parameter
    None