Menu

Expand
Rate 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

Resource Properties in REST API format
sid
sid<ET> Not PII

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

unique_name

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_sid
sid<AC> Not PII

The SID of the Account that created the Document resource.

service_sid
sid<IS> Not PII

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

url
url Not PII

The absolute URL of the Document resource.

links
uri_map Not PII

The URLs of resources related to the Sync Document.

revision
string Not PII

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

data

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

date_expires
date_time<iso8601> Not PII

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_created
date_time<iso8601> Not PII

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

date_updated
date_time<iso8601> Not PII

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

created_by

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
Parameters
Parameters in REST API format
service_sid
Path
post sid_like<IS> Not PII

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

unique_name
Optional
post string PII MTL: 30 DAYS

An application-defined string that uniquely identifies the Sync Document

data
Optional
post object 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.

ttl
Optional
post integer Not PII

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

Example 1
        
        
        
        Example 2
              
              
              

              Using set will overwrite any existing data in a document.

              Fetch a Document resource

              get
              https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
              Parameters
              Parameters in REST API format
              service_sid
              Path
              get sid_like<IS> Not PII

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

              sid
              Path
              get sid_like<ET> Not PII

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

              Example 1
                    
                    
                    
                    Example 2
                          
                          
                          
                          Example 3
                                
                                
                                

                                Read multiple Document resources

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

                                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.

                                Parameters
                                Parameters in REST API format
                                service_sid
                                Path
                                get sid_like<IS> Not PII

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

                                Example 1
                                      
                                      
                                      

                                      Update a Document resource

                                      post
                                      https://sync.twilio.com/v1/Services/{ServiceSid}/Documents/{Sid}
                                      Parameters
                                      Parameters in REST API format
                                      service_sid
                                      Path
                                      post sid_like<IS> Not PII

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

                                      sid
                                      Path
                                      post sid_like<ET> Not PII

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

                                      data
                                      Optional
                                      post object 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.

                                      ttl
                                      Optional
                                      post integer Not PII

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

                                      if_match
                                      Header
                                      post string Not PII

                                      The If-Match HTTP request header

                                      Example 1
                                            
                                            
                                            
                                            Example 2
                                                  
                                                  
                                                  
                                                  This will modify the foregroundColor key in the Document

                                                  Update data in a Document using the JavaScript SDK

                                                  This will modify the foregroundColor key in the Document
                                                  Example 3
                                                        
                                                        
                                                        
                                                        Use mutate for more fine grained control over updates.

                                                        Mutate data in a Document using the JavaScript SDK

                                                        Use mutate for more fine grained control over updates.

                                                        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}
                                                        Parameters
                                                        Parameters in REST API format
                                                        service_sid
                                                        Path
                                                        delete sid_like<IS> Not PII

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

                                                        sid
                                                        Path
                                                        delete sid_like<ET> Not PII

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

                                                        Example 1
                                                              
                                                              
                                                              
                                                              Example 2
                                                                    
                                                                    
                                                                    
                                                                    Rate this page:

                                                                    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 our Twilio Community forums or browsing the Twilio tag on Stack Overflow.

                                                                          
                                                                          
                                                                          

                                                                          Thank you for your feedback!

                                                                          We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                                                          Sending your feedback...
                                                                          🎉 Thank you for your feedback!
                                                                          Something went wrong. Please try again.

                                                                          Thanks for your feedback!

                                                                          Refer us and get $10 in 3 simple steps!

                                                                          Step 1

                                                                          Get link

                                                                          Get a free personal referral link here

                                                                          Step 2

                                                                          Give $10

                                                                          Your user signs up and upgrade using link

                                                                          Step 3

                                                                          Get $10

                                                                          1,250 free SMSes
                                                                          OR 1,000 free voice mins
                                                                          OR 12,000 chats
                                                                          OR more