Service

A Service is the top-level scope of all other resources in the REST API. It owns Sessions and Proxy Numbers (e.g. Phone Numbers and Short Codes) for a Proxy application. Services allow you to:

Create multiple environments (e.g. dev, stage, and prod) under the same Twilio account with segregated data
Scope access to resources through the REST API
Configure behavior of the Service per instance

Service properties

Resource Properties in REST API format
`sid`	sid<KS> Not PII The unique string that we created to identify the Service resource.
`unique_name`	string Not PII An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. Supports UTF-8 characters. This value should not have PII.
`account_sid`	sid<AC> Not PII The SID of the Account that created the Service resource.
`chat_instance_sid`	sid<IS> Not PII The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.
`callback_url`	url Not PII The URL we call when the interaction status changes.
`default_ttl`	integer Not PII The default `ttl` value for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of `0` indicates an unlimited Session length. You can override a Session's default TTL value by setting its `ttl` value.
`number_selection_behavior`	enum:number_selection_behavior Not PII The preference for Proxy Number selection in the Service instance. Can be: `prefer-sticky` or `avoid-sticky`. `prefer-sticky` means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. `avoid-sticky` means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
`geo_match_level`	enum:geo_match_level Not PII Where a proxy number must be located relative to the participant identifier. Can be: `country`, `area-code`, or `extended-area-code`. The default value is `country` and more specific areas than `country` are only available in North America.
`intercept_callback_url`	url Not PII The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.
`out_of_session_callback_url`	url Not PII The URL we call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.
`date_created`	date_time<iso8601> Not PII The ISO 8601 date and time in GMT when the resource was created.
`date_updated`	date_time<iso8601> Not PII The ISO 8601 date and time in GMT when the resource was last updated.
`url`	url Not PII The absolute URL of the Service resource.
`links`	uri_map Not PII The URLs of resources related to the Service.

Note on Proxy Numbers associated with Services

A Twilio Phone Number or Short Code associated with a Proxy Service cannot be associated with other Proxy Services in the same account.

Learning about Proxy Number management

A Proxy Service contains a lot of detailed configuration options regarding Proxy Number selection logic. If you'd like to learn more about how Proxy handles Proxy Numbers, check out the Proxy Number Management explanation page.

Create a Service resource

post

https://proxy.twilio.com/v1/Services

Create a new Service.

Parameters

Parameters in REST API format
`unique_name` Required	post string Not PII An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII.
`default_ttl` Optional	post integer Not PII The default `ttl` value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of `0` indicates an unlimited Session length. You can override a Session's default TTL value by setting its `ttl` value.
`callback_url` Optional	post url Not PII The URL we should call when the interaction status changes.
`geo_match_level` Optional	post enum:geo_match_level Not PII Where a proxy number must be located relative to the participant identifier. Can be: `country`, `area-code`, or `extended-area-code`. The default value is `country` and more specific areas than `country` are only available in North America.
`number_selection_behavior` Optional	post enum:number_selection_behavior Not PII The preference for Proxy Number selection in the Service instance. Can be: `prefer-sticky` or `avoid-sticky` and the default is `prefer-sticky`. `prefer-sticky` means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. `avoid-sticky` means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
`intercept_callback_url` Optional	post url Not PII The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.
`out_of_session_callback_url` Optional	post url Not PII The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.
`chat_instance_sid` Optional	post sid<IS> Not PII The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.

Example 1

Loading Code Sample...

Example JSON response

Create Service

Fetch a Service resource

get

https://proxy.twilio.com/v1/Services/{Sid}

Retrieve a single Service.

Parameters

Parameters in REST API format
`sid` Path	get sid_like<KS> Not PII The Twilio-provided string that uniquely identifies the Service resource to fetch.

Parameters in REST API format

sid

Path

get sid_like<KS> Not PII

The Twilio-provided string that uniquely identifies the Service resource to fetch.

Example 1

Loading Code Sample...

Example JSON response

Fetch Service

Read multiple Service resources

get

https://proxy.twilio.com/v1/Services

Retrieve a list of all Services for a given account.

Example 1

Loading Code Sample...

Example JSON response

Read Service

Update a Service resource

post

https://proxy.twilio.com/v1/Services/{Sid}

Update a Service's configuration.

Parameters

Parameters in REST API format
`sid` Path	post sid<KS> Not PII The Twilio-provided string that uniquely identifies the Service resource to update.
`unique_name` Optional	post string Not PII An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII.
`default_ttl` Optional	post integer Not PII The default `ttl` value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of `0` indicates an unlimited Session length. You can override a Session's default TTL value by setting its `ttl` value.
`callback_url` Optional	post url Not PII The URL we should call when the interaction status changes.
`geo_match_level` Optional	post enum:geo_match_level Not PII Where a proxy number must be located relative to the participant identifier. Can be: `country`, `area-code`, or `extended-area-code`. The default value is `country` and more specific areas than `country` are only available in North America.
`number_selection_behavior` Optional	post enum:number_selection_behavior Not PII The preference for Proxy Number selection in the Service instance. Can be: `prefer-sticky` or `avoid-sticky` and the default is `prefer-sticky`. `prefer-sticky` means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. `avoid-sticky` means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.
`intercept_callback_url` Optional	post url Not PII The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.
`out_of_session_callback_url` Optional	post url Not PII The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.
`chat_instance_sid` Optional	post sid<IS> Not PII The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.

Example 1

Loading Code Sample...

Example JSON response

Update Service

Delete a Service resource

delete

https://proxy.twilio.com/v1/Services/{Sid}

Permanently delete a Service and all children (Sessions, Participants, Interactions). In addition, all associated Proxy Numbers (e.g. Phone Numbers and Short Codes) will become available for assignment to another Service.

Any Message or Call records created during interactions for Sessions in this Service will NOT be deleted automatically. If you want to delete all related Message/Call resources, you must issue direct DELETE requests for the inbound and outbound resources of all child Interactions directly. Once you have deleted a Service, those resource Sids will not be discoverable via Proxy.

Parameters

Parameters in REST API format
`sid` Path	delete sid<KS> Not PII The Twilio-provided string that uniquely identifies the Service resource to delete.

Parameters in REST API format

sid

Path

delete sid<KS> Not PII

The Twilio-provided string that uniquely identifies the Service resource to delete.

Example 1

Loading Code Sample...

Example JSON response

Delete Service

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Parameters

Example 1

Create Service

Parameters

Example 1

Fetch Service

Example 1

Read Service

Parameters

Example 1

Update Service

Parameters

Example 1

Delete Service

Need some help?

Thank you for your feedback!

Thanks for your feedback!