Menu

Rate this page:

Thanks for rating this page!

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

Sync REST: Lists

A list is an ordered collection of individual items, each storing separate JSON objects.

  • Items can be appended, updated, removed and iterated, but not inserted at random position.
  • Each item is limited to 16KB of data.
  • Item read or update access is performed using item index that is internally generated.
  • Index is not guaranteed to be contiguous.
  • Full list modification history is maintained with every change triggering new revision.
  • Strict ordering of all list mutation events and all contained items is guaranteed.
  • Expires and gets deleted automatically, if eviction is configured via TTL parameter. By default, List and its items are persisted permanently.

List Root Properties

Each List object root resource has the following properties. Unique name and expiration date attributes are optional and allowed to be null.

Names in PHP format
sid
sid<ES> Not PII

The unique 34-character SID identifier of the List.

uniqueName

The unique and addressable name of this List. Optional, up to 320 characters long.

accountSid
sid<AC> Not PII

The unique SID identifier of the Twilio Account.

serviceSid
sid<IS> Not PII

The unique SID identifier of the Service Instance that hosts this List object.

url
url Not PII

The absolute URL for this List.

links
uri_map Not PII

A dictionary of URL links to nested resources of this List.

revision
string Not PII

Contains the current revision of this List, represented by a string identifier.

dateExpires
date_time<iso8601> Not PII

Contains the date this List expires and gets deleted automatically. Contains null if the List persists permanently.

dateCreated
date_time<iso8601> Not PII

The date this List was created, given in UTC ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

Specifies the date this List was last updated, given in UTC ISO 8601 format.

createdBy

The identity of the List creator. If the List is created from the client SDK, the value matches the Access Token's identity field. If the List was created from the REST API, the value is system.

Example

{
  "account_sid": "ACxx",
  "service_sid": "ISxx",
  "sid": "ESxx",
  "unique_name": "MyList",
  "revision": "1a",
  "date_created": "2015-11-24T22:18:57Z",
  "date_updated": "2015-11-24T22:19:58Z",
  "date_expires": null,
  "created_by": "system",
  "url": "https://sync.twilio.com/v1/Services/ISxx/Lists/ESxx",
  "links": {
    "items": "https://sync.twilio.com/v1/Services/ISxx/Lists/ESxx/Items",
    "permissions": "https://sync.twilio.com/v1/Services/ISxx/Lists/ESxx/Permissions"
  }
}

List Item Properties

Each List Item resource is nested under the parent List root resource and has the following properties.

Names in PHP format
index
integer Not PII

Contains the automatically generated index of this List Item. Positive integer or zero, guaranteed to be always incrementing. Not guaranteed to be contiguous; the list may have gaps as items are deleted.

accountSid
sid<AC> Not PII

The unique SID identifier of the Twilio Account.

serviceSid
sid<IS> Not PII

The unique SID identifier of the Service Instance that hosts this List object.

listSid
sid<ES> Not PII

The unique 34-character SID identifier of the List containing this Item.

url
url Not PII

The absolute URL for this item.

revision
string Not PII

Contains the current revision of this item, represented by a string identifier.

data

Contains arbitrary user-defined, schema-less data that this List Item stores, represented by a JSON object, up to 16KB.

dateExpires
date_time<iso8601> Not PII

Contains the date this item expires and gets deleted automatically. Contains null if the List persists permanently.

dateCreated
date_time<iso8601> Not PII

The date this item was created, given in UTC ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

Specifies the date this item was last updated, given in UTC ISO 8601 format.

createdBy

The identity of this item's creator. If the List is created from the client SDK, the value matches the Access Token's identity field. If the List was created from the REST API, the value is system.

Example

{
  "account_sid": "ACxx",
  "service_sid": "ISxx",
  "list_sid": "ESxx",
  "index": 7,
  "revision": "1b",
  "date_created": "2015-11-24T22:19:58Z",
  "date_updated": "2015-11-24T22:19:58Z",
  "date_expires": null,
  "created_by": "system",
  "url": "https://sync.twilio.com/v1/Services/ISxx/Lists/ESxx/Items/7",
  "data": {
      <user-defined List Item content>
  }
}

Actions


List All Lists

GET /v1/Services/ISxx/Lists

Retrieve a list of all Lists belonging to this Service Instance.

Note: By default, this will return the first 50 Lists. Supply a PageSize parameter to fetch up to 100 items at once. See paging for more information.

Example

        
        
        
        

        Create a List

        POST /v1/Services/ISxx/List
        

        Create a new List in this Service Instance, optionally giving it a unique name and assigning an expiration deadline.

        Parameters

        Names in PHP format
        uniqueName
        Optional
        post string PII MTL: 30 DAYS

        Human-readable name for this list

        ttl
        Optional
        post integer Not PII

        Alias for collection_ttl. If both are provided, this value is ignored.

        collectionTtl
        Optional
        post integer Not PII

        Time-to-live of this List in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

              
              
              
              

              Retrieve a List

              GET /v1/Services/ISxx/Lists/ESxx|UniqueName
              

              Fetch information about a specific List by its SID or unique name.

              Example

                    
                    
                    
                    

                    Update a List

                    POST /v1/Services/ISxx/Lists/ESxx|UniqueName
                    

                    Update the List expiration deadline, addressed by its SID or unique name.

                    Parameters

                    Names in PHP format
                    ttl
                    Optional
                    post integer Not PII

                    Alias for collection_ttl. If both are provided, this value is ignored.

                    collectionTtl
                    Optional
                    post integer Not PII

                    Time-to-live of this List in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

                          
                          
                          
                          

                          Push Item Into List

                          POST /v1/Services/ISxx/Lists/ESxx|UniqueName/Items
                          

                          Append a new item to this List, supplying its payload, and optionally providing an item expiration deadline.

                          Names in PHP format
                          data
                          Required
                          post object PII MTL: 7 DAYS

                          Contains arbitrary user-defined, schema-less data that this List Item stores, represented by a JSON object, up to 16KB.

                          ttl
                          Optional
                          post integer Not PII

                          Alias for item_ttl. If both are provided, this value is ignored.

                          itemTtl
                          Optional
                          post integer Not PII

                          Time-to-live of this item in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity. Upon expiry, the list item will be cleaned up at least in a matter of hours, and often within seconds, making this a good tool for garbage management.

                          collectionTtl
                          Optional
                          post integer Not PII

                          Time-to-live of this item's parent List in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity. This parameter can only be used when the list item's data or ttl is updated in the same request.

                                
                                
                                
                                

                                Get Item From List

                                GET /v1/Services/ISxx/Lists/ESxx|UniqueName/Items/<INDEX>
                                

                                Fetch data of a specific item in the current List, addressed by List SID (or unique name) and item index.

                                Example

                                      
                                      
                                      
                                      

                                      Query Items From List

                                      GET /v1/Services/ISxx/Lists/ESxx|UniqueName/Items
                                      

                                      Retrieve a list of all items belonging to this List.

                                      Note: By default, this will return the first 50 List items. Supply a PageSize parameter to fetch up to 100 items at once. See paging for more information.

                                      Parameters

                                      Names in PHP format
                                      order
                                      Optional
                                      get enum:query_result_order Not PII

                                      A string; asc or desc

                                      from
                                      Optional
                                      get string Not PII

                                      An integer representing Item index offset (inclusive). If not present, query is performed from the start or end, depending on the Order query parameter.

                                            
                                            
                                            
                                            

                                            Update Item In List

                                            POST /v1/Services/ISxx/Lists/ESxx|UniqueName/Items/<INDEX>
                                            

                                            Update data and/or expiration deadline of a specific item in the current List, addressed by SID (or unique name) and item index.

                                            Parameters

                                            Names in PHP format
                                            data
                                            Optional
                                            post object PII MTL: 7 DAYS

                                            Contains arbitrary user-defined, schema-less data that this List Item stores, represented by a JSON object, up to 16KB.

                                            ttl
                                            Optional
                                            post integer Not PII

                                            Alias for item_ttl. If both are provided, this value is ignored.

                                            itemTtl
                                            Optional
                                            post integer Not PII

                                            Time-to-live of this item in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity. Upon expiry, the list item will be cleaned up at least in a matter of hours, and often within seconds, making this a good tool for garbage management.

                                            collectionTtl
                                            Optional
                                            post integer Not PII

                                            Time-to-live of this item's parent List in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity. This parameter can only be used when the list item's data or ttl is updated in the same request.

                                                  
                                                  
                                                  
                                                  

                                                  Remove Item From List

                                                  DELETE /v1/Services/ISxx/Lists/ESxx|UniqueName/Items/<INDEX>
                                                  

                                                  Permanently delete a specific item from the current List, addressed by SID (or unique name) and item index.

                                                  Example

                                                        
                                                        
                                                        
                                                        

                                                        Delete a List

                                                        DELETE /v1/Services/ISxx/Lists/ESxx|UniqueName
                                                        

                                                        Permanently delete a specific List along with all items belonging to it from current Service Instance, addressed by SID or unique name.

                                                        Example

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