Get Started

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:

Property Description
Sid A 34 character string that uniquely identifies the SIP domain in Twilio.
FriendlyName A human readable descriptive text, up to 64 characters long.
AccountSid The unique id of the Account that sent this message.
ApiVersion The version of the Twilio API used to process the message.
DomainName The unique address you reserve on Twilio to which you route your SIP traffic. Domain names can contain letters, digits, and “-”.
AuthType The 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.
VoiceUrl The URL Twilio will request when this domain receives a call.
VoiceMethod The HTTP method Twilio will use when requesting the above Url. Either GET or POST.
VoiceFallbackUrl The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.
VoiceFallbackMethod The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
VoiceStatusCallback The URL that Twilio will request to pass status parameters (such as call ended) to your application.
VoiceStatusCallbackMethod The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
Uri The 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:

Parameter Description
DomainName The 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.

Parameter Description
FriendlyName A human readable descriptive text, up to 64 characters long.
VoiceUrl The URL Twilio will request when this domain receives a call.
VoiceMethod The HTTP method Twilio will use when requesting the above Url. Either GET or POST.
VoiceFallbackUrl The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.
VoiceFallbackMethod The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
VoiceStatusCallback The URL that Twilio will request to pass status parameters (such as call ended) to your application.
VoiceStatusCallbackMethod The 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:

Property Description
Sid A 34 character string that uniquely identifies an IpAccessControlList you have mapped to the domain
AccountSid The unique id of the Account that responsible for this resource.
FriendlyName The unique id of the Account that responsible for this resource.
DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
Uri The 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:

Parameter Description
IpAccessControlListSid The 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:

Property Description
Sid A 34 character string that uniquely identifies a CredentialList you have mapped to the domain.
AccountSid The unique id of the Account that responsible for this resource.
FriendlyName The unique id of the Account that responsible for this resource.
DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
Uri The 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:

Parameter Description
CredentialListSid The 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