Skip to contentSkip to navigationSkip to topbar
Rate this page:
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

working-with-sync-documents page anchor

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.


Resource properties
sidtype: SID<ET>Not PII

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


unique_nametype: stringPII 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.


service_sidtype: SID<IS>Not PII

The SID of the Sync Service(link takes you to an external page) the resource is associated with.


urltype: string<URI>Not PII

The absolute URL of the Document resource.


linkstype: object<URI MAP>Not PII

The URLs of resources related to the Sync Document.


revisiontype: stringNot PII

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


datatype: objectPII MTL: 7 days

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


date_expirestype: string<DATE TIME>Not PII

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_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


created_bytype: stringPII 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

create-a-document-resource page anchor
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents

Parameters

create-parameters page anchor
URI parameters
ServiceSidtype: stringNot PII
Path Parameter

The SID of the Sync Service(link takes you to an external page) to create the new Document resource in.


Request body parameters
UniqueNametype: stringPII MTL: 30 days

An application-defined string that uniquely identifies the Sync Document


Datatype: objectPII 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.


Ttltype: integerNot PII

How long, in seconds(link takes you to an external page), before the Sync Document expires and is deleted (the Sync Document's time-to-live).

Create a Document using the REST API

create-a-document-using-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.documents
_11
.create({uniqueName: 'user_prefs'})
_11
.then(document => console.log(document.sid));

Output

_16
{
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"created_by": "created_by",
_16
"data": {},
_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": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"unique_name": "user_prefs",
_16
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"links": {
_16
"permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_16
}
_16
}

Create and set Document data using the JavaScript API

create-and-set-document-data-using-the-javascript-api page anchor

_10
client.document('user_prefs').then(function(doc) {
_10
doc.set({
_10
foregroundColor: "#ffff00",
_10
backgroundColor: "#ff0000"
_10
});
_10
});

(information)

Info

Using set will overwrite any existing data in a document.


Fetch a Document resource

fetch-a-document-resource page anchor
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

The SID of the Sync Service(link takes you to an external page) with the Document resource to fetch.


Sidtype: stringNot PII
Path Parameter

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

fetch-a-document-using-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(document => console.log(document.uniqueName));

Output

_16
{
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"created_by": "created_by",
_16
"data": {},
_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": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"unique_name": "unique_name",
_16
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"links": {
_16
"permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_16
}
_16
}

Fetch a Document with the JavaScript SDK

fetch-a-document-with-the-javascript-sdk page anchor

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

Subscribe to Document updates with the JavaScript SDK

subscribe-to-document-updates-with-the-javascript-sdk page anchor

_10
syncClient.document("user_prefs").then(function(doc) {
_10
doc.on("updated",function(data) {
_10
console.log(data);
_10
});
_10
});


Read multiple Document resources

read-multiple-document-resources page anchor
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.

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

The SID of the Sync Service(link takes you to an external page) with the Document resources to read.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Retrieve all Documents using the REST API

retrieve-all-documents-using-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.documents
_11
.list({limit: 20})
_11
.then(documents => documents.forEach(d => console.log(d.sid)));

Output

_29
{
_29
"documents": [
_29
{
_29
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"created_by": "created_by",
_29
"data": {},
_29
"date_expires": "2015-07-30T21:00:00Z",
_29
"date_created": "2015-07-30T20:00:00Z",
_29
"date_updated": "2015-07-30T20:00:00Z",
_29
"revision": "revision",
_29
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"unique_name": "unique_name",
_29
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_29
"links": {
_29
"permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_29
}
_29
}
_29
],
_29
"meta": {
_29
"first_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0",
_29
"key": "documents",
_29
"next_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=1",
_29
"page": 0,
_29
"page_size": 50,
_29
"previous_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0",
_29
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents?PageSize=50&Page=0"
_29
}
_29
}


Update a Document resource

update-a-document-resource page anchor
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}

Request headers
If-Matchtype: stringNot PII

The If-Match HTTP request header


URI parameters
ServiceSidtype: stringNot PII
Path Parameter

The SID of the Sync Service(link takes you to an external page) with the Document resource to update.


Sidtype: stringNot PII
Path Parameter

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


Request body parameters
Datatype: objectPII 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.


Ttltype: integerNot PII

How long, in seconds(link takes you to an external page), before the Sync Document expires and is deleted (time-to-live).

Update a Document using the REST API

update-a-document-using-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({data: {}})
_11
.then(document => console.log(document.uniqueName));

Output

_16
{
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"created_by": "created_by",
_16
"data": {},
_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": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"sid": "ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"unique_name": "unique_name",
_16
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"links": {
_16
"permissions": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Documents/ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Permissions"
_16
}
_16
}

Update data in a Document using the JavaScript SDK

update-data-in-a-document-using-the-javascript-sdk page anchor

This will modify the foregroundColor key in the Document


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

Mutate data in a Document using the JavaScript SDK

mutate-data-in-a-document-using-the-javascript-sdk page anchor

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";
_10
return remoteData;
_10
});
_10
});

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-a-document-resource page anchor
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

The SID of the Sync Service(link takes you to an external page) with the Document resource to delete.


Sidtype: stringNot PII
Path Parameter

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

delete-a-document-using-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.documents('ETXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();

Remove a Document with the JavaScript SDK

remove-a-document-with-the-javascript-sdk page anchor

_10
syncClient.document("user_prefs").then(function(doc) {
_10
doc.removeDocument().then(function() {
_10
console.log('Document removed.');
_10
});
_10
});


Rate this page: