Skip to content Skip to navigation Skip to topbar

On this page

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.

Working with Sync Documents

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.

Document Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<ET>

Optional

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

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

unique_namestring

Optional

PII MTL: 30 days

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.

account_sidSID<AC>

Optional

The SID of the Account that created the Document resource.

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

service_sidSID<IS>

Optional

The SID of the Sync Service the resource is associated with.

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

urlstring<uri>

Optional

The absolute URL of the Document resource.

linksobject<uri-map>

Optional

The URLs of resources related to the Sync Document.

revisionstring

Optional

The current revision of the Sync Document, represented as a string. The revision property is used with conditional updates to ensure data consistency.

dataobject

Optional

PII MTL: 7 days

An arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.

date_expiresstring<date-time>

Optional

The date and time in GMT when the Sync Document expires and will be deleted, specified in ISO 8601 format. If the Sync Document does not expire, this value is null. The Document resource might not be deleted immediately after it expires.

date_createdstring<date-time>

Optional

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

date_updatedstring<date-time>

Optional

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

created_bystring

Optional

PII MTL: 30 days

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.

Create a Document resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidstringrequired

The SID of the Sync Service to create the new Document resource in.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

UniqueNamestring

Optional

PII MTL: 30 days

An application-defined string that uniquely identifies the Sync Document

Dataobject

Optional

PII MTL: 7 days

A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.

Ttlinteger

Optional

How long, in seconds, before the Sync Document expires and is deleted (the Sync Document's time-to-live).

Create a Document using the REST API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createDocument() {
11  const document = await client.sync.v1
12    .services("ServiceSid")
13    .documents.create({ uniqueName: "user_prefs" });
14
15  console.log(document.sid);
16}
17
18createDocument();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "created_by": "created_by",
4  "data": {},
5  "date_expires": "2015-07-30T21:00:00Z",
6  "date_created": "2015-07-30T20:00:00Z",
7  "date_updated": "2015-07-30T20:00:00Z",
8  "revision": "revision",
9  "service_sid": "ServiceSid",
10  "sid": "ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
11  "unique_name": "user_prefs",
12  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "links": {
14    "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
15  }
16}

Create and set Document data using the JavaScript API

1client.document('user_prefs').then(function(doc) {
2  doc.set({
3    foregroundColor: "#ffff00",
4    backgroundColor: "#ff0000"
5  });
6});

(information)

Info

Using set will overwrite any existing data in a document.

Fetch a Document resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidstringrequired

The SID of the Sync Service with the Document resource to fetch.

Sidstringrequired

The SID of the Document resource to fetch. Can be the Document resource's sid or its unique_name.

Fetch a Document using the REST API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchDocument() {
11  const document = await client.sync.v1
12    .services("ServiceSid")
13    .documents("Sid")
14    .fetch();
15
16  console.log(document.sid);
17}
18
19fetchDocument();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "created_by": "created_by",
4  "data": {},
5  "date_expires": "2015-07-30T21:00:00Z",
6  "date_created": "2015-07-30T20:00:00Z",
7  "date_updated": "2015-07-30T20:00:00Z",
8  "revision": "revision",
9  "service_sid": "ServiceSid",
10  "sid": "Sid",
11  "unique_name": "unique_name",
12  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "links": {
14    "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
15  }
16}

Fetch a Document with the JavaScript SDK

1client.document('user_prefs').then(function(doc) {
2  console.log(doc.value);
3});

Read multiple Document resources

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

(information)

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.

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidstringrequired

The SID of the Sync Service with the Document resources to read.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

Retrieve all Documents using the REST API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listDocument() {
11  const documents = await client.sync.v1
12    .services("ServiceSid")
13    .documents.list({ limit: 20 });
14
15  documents.forEach((d) => console.log(d.sid));
16}
17
18listDocument();

Output

1{
2  "documents": [],
3  "meta": {
4    "first_page_url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents?PageSize=50&Page=0",
5    "key": "documents",
6    "next_page_url": null,
7    "page": 0,
8    "page_size": 50,
9    "previous_page_url": null,
10    "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents?PageSize=50&Page=0"
11  }
12}

Update a Document resource

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

Headers

Property nameTypeRequiredPIIDescription

If-Matchstring

Optional

The If-Match HTTP request header

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidstringrequired

The SID of the Sync Service with the Document resource to update.

Sidstringrequired

The SID of the Document resource to update. Can be the Document resource's sid or its unique_name.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Dataobject

Optional

PII MTL: 7 days

A JSON string that represents an arbitrary, schema-less object that the Sync Document stores. Can be up to 16 KiB in length.

Ttlinteger

Optional

How long, in seconds, before the Sync Document expires and is deleted (time-to-live).

Update a Document using the REST API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateDocument() {
11  const document = await client.sync.v1
12    .services("ServiceSid")
13    .documents("Sid")
14    .update({ data: {} });
15
16  console.log(document.sid);
17}
18
19updateDocument();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "created_by": "created_by",
4  "data": {},
5  "date_expires": "2015-07-30T21:00:00Z",
6  "date_created": "2015-07-30T20:00:00Z",
7  "date_updated": "2015-07-30T20:00:00Z",
8  "revision": "revision",
9  "service_sid": "ServiceSid",
10  "sid": "Sid",
11  "unique_name": "unique_name",
12  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "links": {
14    "permissions": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Documents/ETaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Permissions"
15  }
16}

Update data in a Document using the JavaScript SDK

This will modify the foregroundColor key in the Document

1client.document('user_prefs').then(function(doc) {
2  doc.update({foregroundColor: "#ff0000"});
3});

Mutate data in a Document using the JavaScript SDK

Use mutate for more fine grained control over updates.

1client.document('user_prefs').then(function(doc) {
2  doc.mutate(function(remoteData) {
3    remoteData.foregroundColor = "#e2e2e2";
4    return remoteData;
5  });
6});

The mutate function helps your JavaScript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.

Delete a Document resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidstringrequired

The SID of the Sync Service with the Document resource to delete.

Sidstringrequired

The SID of the Document resource to delete. Can be the Document resource's sid or its unique_name.

Delete a Document using the REST API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteDocument() {
11  await client.sync.v1.services("ServiceSid").documents("Sid").remove();
12}
13
14deleteDocument();

Remove a Document with the JavaScript SDK

1syncClient.document("user_prefs").then(function(doc) {
2  doc.removeDocument().then(function() {
3    console.log('Document removed.');
4  });
5});