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://bryan.lvh.me/api/relay/rest/addresses \
  -X POST
  -H 'Content-Type: application/json' \
  -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.

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
}

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.

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
}

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
}

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
    },
    {...},
    {...}
  ]
}

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"
}
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.

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"
    },
    {...},
    {...}
  ]
}

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[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.

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.