Navbar
Logo icon Name

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.

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 Phone 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 Phone 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 Membershpi. 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 required The name given to the number group to distinguish different groups 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.

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": {
    "carrier_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",
    "ILBC",
    "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",
    "ILBC",
    "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, ILBC, 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",
    "ILBC",
    "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, ILBC, 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",
        "ILBC",
        "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.