REST API: SIP Domains

Overview

A SIP domain is a custom DNS hostname that can accept SIP traffic for your account. If anyone makes a SIP request to that domain, for example to “sip:alice@example.sip.twilio.com”, it will route to Twilio. When that request hits Twilio, it’s authenticated, and then Twilio requests TwiML from your server. The VoiceUrl of the SIP domain tells Twilio what URL to request.

Twilio has two built-in authentication methods for your SIP Domain: IpAccessControlLists and CredentialLists. You must have at least one mapped to your Domain or else all requests will be blocked. You may apply one or multiple of each type to each SIP Domain.

The IpAccessControlListMappings and CredentialListMappings subresources of the SIP Domain show which lists are mapped to your SIP Domain.

Resource Properties

A Domain instance resource has the following properties:

PropertyDescription
SidA 34 character string that uniquely identifies the SIP domain in Twilio.
FriendlyNameA human readable descriptive text, up to 64 characters long.
AccountSidThe unique id of the Account that sent this message.
ApiVersionThe version of the Twilio API used to process the message.
DomainNameThe unique address you reserve on Twilio to which you route your SIP traffic. Domain names can contain letters, digits, and “-”.
AuthTypeThe types of authentication you have mapped to your domain. The possible values are “IP_ACL” and “CREDENTIAL_LIST”. If you have both setup for your domain, both will be returned comma delimited. If you do not, have one setup for your domain, it will not be able to receive any traffic.
VoiceUrlThe URL Twilio will request when this domain receives a call.
VoiceMethodThe HTTP method Twilio will use when requesting the above Url. Either GET or POST.
VoiceFallbackUrlThe URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.
VoiceFallbackMethodThe HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
VoiceStatusCallbackUrlThe URL that Twilio will request to pass status parameters (such as call ended) to your application.
VoiceStatusCallbackMethodThe HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
DateCreatedThe date that this resource was created, given as GMT in RFC 2822 format.
DateUpdatedThe date that this resource was last updated, given as GMT in RFC 2822 format.
UriThe URI for this resource, relative to https://api.twilio.com

SIP Domain List Resource

The list resource allows you to view the domains in an account as well as create new domains.

Resource URI

/2010-04-01/Accounts/{AccountSid}/SIP/Domains

HTTP GET

GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains

Returns a paged list of the domains for an account.

Example

Get a list of all domains.

HTTP POST

Creates a new Domain and returns its instance resource. You must pick a unique domain name that ends in “.sip.twilio.com”. After creating a Domain, you must map it to an authentication method before the domain is ready to receive traffic.

POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains

You must POST at least the following to create a new Domain:

ParameterDescription
DomainNameThe unique address you reserve on Twilio to which you route your SIP traffic. Domain names can contain letters, digits, and “-”.

You may also set the following when creating your Domain. We recommend that you at least set the VoiceUrl of your Domain when creating it.

ParameterDescription
FriendlyNameA human readable descriptive text, up to 64 characters long.
VoiceUrlThe URL Twilio will request when this domain receives a call.
VoiceMethodThe HTTP method Twilio will use when requesting the above Url. Either GET or POST.
VoiceFallbackUrlThe URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.
VoiceFallbackMethodThe HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
VoiceStatusCallbackUrlThe URL that Twilio will request to pass status parameters (such as call ended) to your application.
VoiceStatusCallbackMethodThe HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
Example

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

Domain Instance Resource

The SIP/Domain instance resource allows you to view, modify and delete a single domain.

The instance resource is represented by the properties above.

Resource URI

/2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}

HTTP GET

Return a specific instance by Sid.

GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
Example

HTTP POST

Update the attributes of a domain.

POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
Example

HTTP PUT

Not supported.

HTTP DELETE

Delete a domain. If you have created subdomains of a domain, you will not be able to delete the domain until you first delete all subdomains of it.

If successful, Twilio will return an HTTP 204 response with no body.

DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
Example

Domain Instance Subresources

Domain IpAccessControlListMappings List Subresource

The IpAccessControlListMappings subresource contains the list of IpAccessControlList instances associated with this domain. If an INVITE is received for a domain, the source IP address must be in one of the mapped lists for the INVITE to be accepted.

Resource URI

/2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/IpAccessControlListMappings

Resource Properties

An IpAccessControlListMappings resource is represented by the following properties:

PropertyDescription
SidA 34 character string that uniquely identifies an IpAccessControlList you have mapped to the domain
AccountSidThe unique id of the Account that responsible for this resource.
FriendlyNameThe unique id of the Account that responsible for this resource.
DateCreatedThe date that this resource was created, given as GMT in RFC 2822 format.
DateUpdatedThe date that this resource was last updated, given as GMT in RFC 2822 format.
UriThe URI for this resource, relative to https://api.twilio.com

HTTP GET

Return the IpAccessControlListMappings that are associated to this domain.

GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/IpAccessControlListMappings

Return a specific instance by Sid.

Example

HTTP POST

Map an IpAccessControlList to this domain.

POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/IpAccessControlListMappings
POST Parameters

The following parameters are required in your POST to IpAccessControlListMappings:

ParameterDescription
IpAccessControlListSidThe Sid of the IpAccessControlList that you want to associated with this domain. Once associated, Twilio will start authenticating access to the domain against this list.

Example

HTTP PUT

Not supported.

HTTP DELETE

Remove a mapping from this domain.

DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/IpAccessControlListMappings/{ALSid}
Example

Domain CredentialListMappings List Subresource

The CredentialListMappings subresource represents the CredentialLists instances associated with this domain. If an INVITE is received for a domain with a Credential List mapped to it, Twilio will challenge the request. Your system will need to authenticate with a username and password. The username and password must be in one of the mapped lists for the INVITE to be accepted.

Resource URI

/2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/CredentialListMappings

Resource Properties

A CredentialListMappings resource is represented by the following properties:

PropertyDescription
SidA 34 character string that uniquely identifies a CredentialList you have mapped to the domain.
AccountSidThe unique id of the Account that responsible for this resource.
FriendlyNameThe unique id of the Account that responsible for this resource.
DateCreatedThe date that this resource was created, given as GMT in RFC 2822 format.
DateUpdatedThe date that this resource was last updated, given as GMT in RFC 2822 format.
UriThe URI for this resource, relative to https://api.twilio.com

HTTP GET

Get the user lists mapped to this domain.

GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/CredentialListMappings
Example

HTTP POST

Map a CredentialList to the domain.

POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/CredentialListMappings
POST Parameters

The following parameters are required in your POST to CredentialListMappings:

ParameterDescription
CredentialListSidThe Sid of the CredentialList that you want to associated with this domain. Once associated, Twilio will start authenticating access to the domain against this list.

Example

HTTP PUT

Not supported.

HTTP DELETE

DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/CredentialListMappings/{CLSid}

Remove a CredentialListMapping from a domain

Example