Document Resource
A Sync Document is an object with these characteristics:
It's a single JSON object, up to 16KiB in size.
Its modification history is not maintained; however, documents are assigned a new revision number after each modification.
Its concurrency control is based on an 'eventual' model and it uses revision numbers for conditional updates.
It expires and is deleted automatically if its eviction is configured by setting the
ttl
parameter. By default, it is persisted permanently.
A Sync Document is best suited for basic use cases, such as rudimentary publish/subscribe flows, or situations where history synchronization is not a requirement.
Documents can be created, updated, subscribed to, and removed via the client JavaScript SDK . See the latest JavaScript SDK documentation for full details. Servers wishing to manage these objects can do so via the REST API.
Property name Type PII Description
The unique string that we created to identify the Document resource.
Pattern: ^ET[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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 and can be up to 320 characters long.
The SID of the Account that created the Document resource.
Pattern: ^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Sync Service the resource is associated with.
Pattern: ^IS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The absolute URL of the Document resource.
The URLs of resources related to the Sync Document.
The current revision of the Sync Document, represented as a string. The revision
property is used with conditional updates to ensure data consistency.
An arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
date_expires string<date-time> The date and time in GMT when the Sync Document expires and will be deleted, specified in ISO 8601(link takes you to an external page) format. If the Sync Document does not expire, this value is null
. The Document resource might not be deleted immediately after it expires.
date_created string<date-time> date_updated string<date-time> The identity of the Sync Document's creator. If the Sync Document is created from the client SDK, the value matches the Access Token's identity
field. If the Sync Document was created from the REST API, the value is system
.
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents
Property name Type Required PII Description
The SID of the Sync Service to create the new Document resource in.
Property name Type Required PII Description
An application-defined string that uniquely identifies the Sync Document
A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
How long, in seconds , before the Sync Document expires and is deleted (the Sync Document's time-to-live).
_18 // Download the helper library from https://www.twilio.com/docs/node/install
_18 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18 // Find your Account SID and Auth Token at twilio.com/console
_18 // and set the environment variables. See http://twil.io/secure
_18 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18 const authToken = process.env.TWILIO_AUTH_TOKEN;
_18 const client = twilio(accountSid, authToken);
_18 async function createDocument() {
_18 const document = await client.sync.v1
_18 .services("ServiceSid")
_18 .documents.create({ uniqueName: "user_prefs" });
_18 console.log(document.sid);
_16 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ServiceSid",
_16 "sid": "ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "unique_name": "user_prefs",
_16 "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
_10 client.document('user_prefs').then(function(doc) {
_10 foregroundColor: "#ffff00",
_10 backgroundColor: "#ff0000"
Info Using set will overwrite any existing data in a document.
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
Property name Type Required PII Description
The SID of the Sync Service with the Document resource to fetch.
The SID of the Document resource to fetch. Can be the Document resource's sid
or its unique_name
.
_19 // Download the helper library from https://www.twilio.com/docs/node/install
_19 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19 // Find your Account SID and Auth Token at twilio.com/console
_19 // and set the environment variables. See http://twil.io/secure
_19 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19 const authToken = process.env.TWILIO_AUTH_TOKEN;
_19 const client = twilio(accountSid, authToken);
_19 async function fetchDocument() {
_19 const document = await client.sync.v1
_19 .services("ServiceSid")
_19 console.log(document.sid);
_16 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ServiceSid",
_16 "unique_name": "unique_name",
_16 "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
_10 client.document('user_prefs').then(function(doc) {
_10 console.log(doc.value);
_10 syncClient.document("user_prefs").then(function(doc) {
_10 doc.on("updated",function(data) {
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Documents
Info By default, this will return the first 50 Documents. Specify a PageSize
value to fetch up to 100 items at once. See paging for more information.
Property name Type Required PII Description
The SID of the Sync Service with the Document resources to read.
Property name Type Required PII Description
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Minimum: 1
Maximum: 1000
The page index. This value is simply for client state.
Minimum: 0
The page token. This is provided by the API.
_18 // Download the helper library from https://www.twilio.com/docs/node/install
_18 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18 // Find your Account SID and Auth Token at twilio.com/console
_18 // and set the environment variables. See http://twil.io/secure
_18 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18 const authToken = process.env.TWILIO_AUTH_TOKEN;
_18 const client = twilio(accountSid, authToken);
_18 async function listDocument() {
_18 const documents = await client.sync.v1
_18 .services("ServiceSid")
_18 .documents.list({ limit: 20 });
_18 documents.forEach((d) => console.log(d.sid));
_12 "first_page_url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents?PageSize=50&Page=0",
_12 "next_page_url": null,
_12 "previous_page_url": null,
_12 "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents?PageSize=50&Page=0"
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
Property name Type Required PII Description
The SID of the Sync Service with the Document resource to update.
The SID of the Document resource to update. Can be the Document resource's sid
or its unique_name
.
Property name Type Required PII Description
A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.
How long, in seconds , before the Sync Document expires and is deleted (time-to-live).
_19 // Download the helper library from https://www.twilio.com/docs/node/install
_19 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19 // Find your Account SID and Auth Token at twilio.com/console
_19 // and set the environment variables. See http://twil.io/secure
_19 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19 const authToken = process.env.TWILIO_AUTH_TOKEN;
_19 const client = twilio(accountSid, authToken);
_19 async function updateDocument() {
_19 const document = await client.sync.v1
_19 .services("ServiceSid")
_19 .update({ data: {} });
_19 console.log(document.sid);
_16 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "created_by": "created_by",
_16 "date_expires": "2015-07-30T21:00:00Z",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "revision": "revision",
_16 "service_sid": "ServiceSid",
_16 "unique_name": "unique_name",
_16 "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16 "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
This will modify the foregroundColor key in the Document
_10 client.document('user_prefs').then(function(doc) {
_10 doc.update({foregroundColor: "#ff0000"});
Use mutate for more fine grained control over updates.
_10 client.document('user_prefs').then(function(doc) {
_10 doc.mutate(function(remoteData) {
_10 remoteData.foregroundColor = "#e2e2e2";
The mutate
function helps your Javascript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
Property name Type Required PII Description
The SID of the Sync Service with the Document resource to delete.
The SID of the Document resource to delete. Can be the Document resource's sid
or its unique_name
.
_14 // Download the helper library from https://www.twilio.com/docs/node/install
_14 const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14 // Find your Account SID and Auth Token at twilio.com/console
_14 // and set the environment variables. See http://twil.io/secure
_14 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14 const authToken = process.env.TWILIO_AUTH_TOKEN;
_14 const client = twilio(accountSid, authToken);
_14 async function deleteDocument() {
_14 await client.sync.v1.services("ServiceSid").documents("Sid").remove();
_10 syncClient.document("user_prefs").then(function(doc) {
_10 doc.removeDocument().then(function() {
_10 console.log('Document removed.');