On this page

Service Resource

A Service is the top-level scope of all other resources in the REST API. It contains all the objects in a Sync application. Services allow you to:

Create multiple environments (dev, stage, prod) under the same Twilio account with segregated data
Scope access to resources through the REST API
Configure the behavior of those resources in the scope of a Service

Service Properties

Property nameTypePIIDescription

sidSID<IS>

Not PII

The unique string that we created to identify the Service resource.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

unique_namestring

Not PII

An application-defined string that uniquely identifies the resource. It can be used in place of the resource's sid in the URL to address the resource. It is a read-only property, it cannot be assigned using REST API.

account_sidSID<AC>

Not PII

The SID of the Account that created the Service resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendly_namestring

PII MTL: 7 days

The string that you assigned to describe the resource.

date_createdstring<date-time>

Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>

Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

urlstring<uri>

Not PII

The absolute URL of the Service resource.

webhook_urlstring<uri>

Not PII

The URL we call when Sync objects are manipulated.

webhooks_from_rest_enabledboolean

Not PII

Whether the Service instance should call webhook_url when the REST API is used to update Sync objects. The default is false.

reachability_webhooks_enabledboolean

Not PII

Whether the service instance calls webhook_url when client endpoints connect to Sync. The default is false.

acl_enabledboolean

Not PII

Whether token identities in the Service must be granted access to Sync objects by using the Permissions resource. It is disabled (false) by default.

reachability_debouncing_enabledboolean

Not PII

Whether every endpoint_disconnected event should occur after a configurable delay. The default is false, where the endpoint_disconnected event occurs immediately after disconnection. When true, intervening reconnections can prevent the endpoint_disconnected event.

reachability_debouncing_windowinteger

Not PII

The reachability event delay in milliseconds if reachability_debouncing_enabled = true. Must be between 1,000 and 30,000 and defaults to 5,000. This is the number of milliseconds after the last running client disconnects, and a Sync identity is declared offline, before webhook_url is called, if all endpoints remain offline. A reconnection from the same identity by any endpoint during this interval prevents the reachability event from occurring.

linksobject<uri-map>

Not PII

The URLs of related resources.

Create a Service resource

POST https://sync.twilio.com/v1/Services

Request body parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringOptional

PII MTL: 7 days

A string that you assign to describe the resource.

WebhookUrlstring<uri>Optional

Not PII

The URL we should call when Sync objects are manipulated.

ReachabilityWebhooksEnabledbooleanOptional

Not PII

Whether the service instance should call webhook_url when client endpoints connect to Sync. The default is false.

AclEnabledbooleanOptional

Not PII

Whether token identities in the Service must be granted access to Sync objects by using the Permissions resource.

ReachabilityDebouncingEnabledbooleanOptional

Not PII

ReachabilityDebouncingWindowintegerOptional

Not PII

The reachability event delay in milliseconds if reachability_debouncing_enabled = true. Must be between 1,000 and 30,000 and defaults to 5,000. This is the number of milliseconds after the last running client disconnects, and a Sync identity is declared offline, before the webhook_url is called if all endpoints remain offline. A reconnection from the same identity by any endpoint during this interval prevents the call to webhook_url.

WebhooksFromRestEnabledbooleanOptional

Not PII

Whether the Service instance should call webhook_url when the REST API is used to update Sync objects. The default is false.

Create Service resource

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function createService() {
_16  const service = await client.sync.v1.services.create();
_16
_16  console.log(service.sid);
_16}
_16
_16createService();

Output


_21{
_21  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "date_created": "2015-07-30T20:00:00Z",
_21  "date_updated": "2015-07-30T20:00:00Z",
_21  "friendly_name": "friendly_name",
_21  "links": {
_21    "documents": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents",
_21    "lists": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists",
_21    "maps": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps",
_21    "streams": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams"
_21  },
_21  "sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "unique_name": "unique_name",
_21  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "webhook_url": "http://www.example.com",
_21  "webhooks_from_rest_enabled": false,
_21  "reachability_webhooks_enabled": false,
_21  "acl_enabled": true,
_21  "reachability_debouncing_enabled": false,
_21  "reachability_debouncing_window": 5000
_21}

Create Service resource with a webhook URL

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function createService() {
_18  const service = await client.sync.v1.services.create({
_18    webhookUrl: "https://example.com/sync",
_18  });
_18
_18  console.log(service.sid);
_18}
_18
_18createService();

Output


_21{
_21  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "date_created": "2015-07-30T20:00:00Z",
_21  "date_updated": "2015-07-30T20:00:00Z",
_21  "friendly_name": "friendly_name",
_21  "links": {
_21    "documents": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents",
_21    "lists": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists",
_21    "maps": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps",
_21    "streams": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams"
_21  },
_21  "sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "unique_name": "unique_name",
_21  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "webhook_url": "https://example.com/sync",
_21  "webhooks_from_rest_enabled": false,
_21  "reachability_webhooks_enabled": false,
_21  "acl_enabled": true,
_21  "reachability_debouncing_enabled": false,
_21  "reachability_debouncing_window": 5000
_21}

Fetch a Service resource

GET https://sync.twilio.com/v1/Services/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

Not PII

The SID of the Service resource to fetch.

Fetch a Service

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function fetchService() {
_16  const service = await client.sync.v1.services("Sid").fetch();
_16
_16  console.log(service.sid);
_16}
_16
_16fetchService();

Output


_21{
_21  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "date_created": "2015-07-30T20:00:00Z",
_21  "date_updated": "2015-07-30T20:00:00Z",
_21  "friendly_name": "friendly_name",
_21  "links": {
_21    "documents": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents",
_21    "lists": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists",
_21    "maps": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps",
_21    "streams": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams"
_21  },
_21  "sid": "Sid",
_21  "unique_name": "unique_name",
_21  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "webhook_url": "http://www.example.com",
_21  "webhooks_from_rest_enabled": false,
_21  "reachability_webhooks_enabled": false,
_21  "acl_enabled": false,
_21  "reachability_debouncing_enabled": false,
_21  "reachability_debouncing_window": 5000
_21}

Read multiple Service resources

GET https://sync.twilio.com/v1/Services

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

List multiple Services

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function listService() {
_16  const services = await client.sync.v1.services.list({ limit: 20 });
_16
_16  services.forEach((s) => console.log(s.sid));
_16}
_16
_16listService();

Output


_12{
_12  "meta": {
_12    "first_page_url": "https://sync.twilio.com/v1/Services?PageSize=50&Page=0",
_12    "key": "services",
_12    "next_page_url": null,
_12    "page": 0,
_12    "page_size": 50,
_12    "previous_page_url": null,
_12    "url": "https://sync.twilio.com/v1/Services?PageSize=50&Page=0"
_12  },
_12  "services": []
_12}

Update a Service resource

POST https://sync.twilio.com/v1/Services/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

Not PII

The SID of the Service resource to update.

Request body parameters

Property nameTypeRequiredPIIDescription

WebhookUrlstring<uri>Optional

Not PII

The URL we should call when Sync objects are manipulated.

FriendlyNamestringOptional

PII MTL: 7 days

A string that you assign to describe the resource.

ReachabilityWebhooksEnabledbooleanOptional

Not PII

Whether the service instance should call webhook_url when client endpoints connect to Sync. The default is false.

AclEnabledbooleanOptional

Not PII

Whether token identities in the Service must be granted access to Sync objects by using the Permissions resource.

ReachabilityDebouncingEnabledbooleanOptional

Not PII

ReachabilityDebouncingWindowintegerOptional

Not PII

The reachability event delay in milliseconds if reachability_debouncing_enabled = true. Must be between 1,000 and 30,000 and defaults to 5,000. This is the number of milliseconds after the last running client disconnects, and a Sync identity is declared offline, before the webhook is called if all endpoints remain offline. A reconnection from the same identity by any endpoint during this interval prevents the webhook from being called.

WebhooksFromRestEnabledbooleanOptional

Not PII

Whether the Service instance should call webhook_url when the REST API is used to update Sync objects. The default is false.

Update a Service

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function updateService() {
_18  const service = await client.sync.v1
_18    .services("Sid")
_18    .update({ webhookUrl: "https://www.example.com" });
_18
_18  console.log(service.sid);
_18}
_18
_18updateService();

Output


_21{
_21  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "date_created": "2015-07-30T20:00:00Z",
_21  "date_updated": "2015-07-30T20:00:00Z",
_21  "friendly_name": "friendly_name",
_21  "links": {
_21    "documents": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents",
_21    "lists": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists",
_21    "maps": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps",
_21    "streams": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams"
_21  },
_21  "sid": "Sid",
_21  "unique_name": "unique_name",
_21  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_21  "webhook_url": "https://www.example.com",
_21  "webhooks_from_rest_enabled": false,
_21  "reachability_webhooks_enabled": false,
_21  "acl_enabled": true,
_21  "reachability_debouncing_enabled": false,
_21  "reachability_debouncing_window": 5000
_21}

Delete a Service resource

DELETE https://sync.twilio.com/v1/Services/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

Not PII

The SID of the Service resource to delete.

Delete a Service

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = twilio(accountSid, authToken);
_14
_14async function deleteService() {
_14  await client.sync.v1.services("Sid").remove();
_14}
_14
_14deleteService();