Menu

Expand
Rate this page:

ListItem resource

A Sync ListItem is an object you have added to a Sync List.

You need to create a List before you can use this resource to create, read, update, and delete items within it.

Sync Lists generally behave like arrays in most programming languages. However, working with ListItems, keep these details in mind:

  • 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 an item index that is internally generated.
  • The 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.
  • Lists expire and are deleted automatically, if you included a TTL parameter when creating your List. By default, a List and its items are persisted permanently.

ListItem properties

Resource Properties in REST API format
index
integer Not PII

The automatically generated index of the List Item. The index values of the List Items in a Sync List can have gaps in their sequence.

account_sid
sid<AC> Not PII

The SID of the Account that created the List Item resource.

service_sid
sid<IS> Not PII

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

list_sid
sid<ES> Not PII

The SID of the Sync List that contains the List Item.

url
url Not PII

The absolute URL of the List Item resource.

revision
string Not PII

The current revision of the item, represented as a string.

data

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

date_expires
date_time<iso8601> Not PII

The date and time in GMT when the List Item expires and will be deleted, specified in ISO 8601 format. If the List Item does not expire, this value is null. The List Item 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 List Item's creator. If the item is created from the client SDK, the value matches the Access Token's identity field. If the item was created from the REST API, the value is system.

Create a ListItem resource

post
https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items
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 List Item in.

list_sid
Path
post sid_like<ES> Not PII

The SID of the Sync List to add the new List Item to. Can be the Sync List resource's sid or its unique_name.

data
Required
post object PII MTL: 7 DAYS

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

ttl
Optional
post integer Not PII

An alias for item_ttl. If both parameters are provided, this value is ignored.

item_ttl
Optional
post integer Not PII

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

collection_ttl
Optional
post integer Not PII

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

Example 1
        
        
        
        Example 2
              
              
              
              Example 3
                    
                    
                    
                    Note: There are two separate events for list item adds and list item updates:

                    Subscribe to a ListItem addition with the JavaScript SDK

                    Note: There are two separate events for list item adds and list item updates:

                    Fetch a ListItem resource

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

                    The SID of the Sync Service with the Sync List Item resource to fetch.

                    list_sid
                    Path
                    get sid_like<ES> Not PII

                    The SID of the Sync List with the Sync List Item resource to fetch. Can be the Sync List resource's sid or its unique_name.

                    index
                    Path
                    get integer Not PII

                    The index of the Sync List Item resource to fetch.

                    Example 1
                          
                          
                          
                          Fetch only the first item

                          Fetch a ListItem with the REST API

                          Fetch only the first item
                          Example 2
                                
                                
                                
                                Fetch only the first item

                                Fetch a ListItem with the JavaScript SDK

                                Fetch only the first item

                                Read multiple ListItem resources

                                get
                                https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items

                                Retrieve all items belonging to a List.

                                By default, this will return the first 50 List items. Supply a PageSize argument 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 List Item resources to read.

                                list_sid
                                Path
                                get sid_like<ES> Not PII

                                The SID of the Sync List with the List Items to read. Can be the Sync List resource's sid or its unique_name.

                                order
                                Optional
                                get enum:query_result_order Not PII

                                How to order the List Items returned by their index value. Can be: asc (ascending) or desc (descending) and the default is ascending.

                                from
                                Optional
                                get string Not PII

                                The index of the first Sync List Item resource to read. See also bounds.

                                bounds
                                Optional
                                get enum:query_from_bound_type Not PII

                                Whether to include the List Item referenced by the from parameter. Can be: inclusive to include the List Item referenced by the from parameter or exclusive to start with the next List Item. The default value is inclusive.

                                Example 1
                                      
                                      
                                      
                                      Get 20 items from a SyncList

                                      Get ListItems using the REST API

                                      Get 20 items from a SyncList
                                      Example 2
                                            
                                            
                                            
                                            Display the first item only

                                            Get ListItems using the JavaScript SDK

                                            Display the first item only

                                            Update a ListItem resource

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

                                            The SID of the Sync Service with the Sync List Item resource to update.

                                            list_sid
                                            Path
                                            post sid_like<ES> Not PII

                                            The SID of the Sync List with the Sync List Item resource to update. Can be the Sync List resource's sid or its unique_name.

                                            index
                                            Path
                                            post integer Not PII

                                            The index of the Sync List Item resource to update.

                                            data
                                            Optional
                                            post object PII MTL: 7 DAYS

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

                                            ttl
                                            Optional
                                            post integer Not PII

                                            An alias for item_ttl. If both parameters are provided, this value is ignored.

                                            item_ttl
                                            Optional
                                            post integer Not PII

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

                                            collection_ttl
                                            Optional
                                            post integer Not PII

                                            How long, in seconds, before the List Item's parent Sync List expires (time-to-live) and is deleted. This parameter can only be used when the List Item's data or ttl is updated in the same request.

                                            if_match
                                            Header
                                            post string Not PII

                                            If provided, applies this mutation if (and only if) the “revision” field of this [map item] matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header.

                                            Example 1
                                                  
                                                  
                                                  
                                                  Example 2
                                                        
                                                        
                                                        
                                                        Use the set method to change the data in a ListItem

                                                        Change data in a single ListItem with the JavaScript SDK

                                                        Use the set method to change the data in a ListItem

                                                        Please note: Using set will overwrite any existing data in a list item.

                                                        Example 3
                                                              
                                                              
                                                              
                                                              Use the update method to change data in a ListItem.

                                                              Update data in a ListItem with the JavaScript SDK

                                                              Use the update method to change data in a ListItem.
                                                              Example 4
                                                                    
                                                                    
                                                                    
                                                                    Use mutate for more fine-grained control

                                                                    Mutate data in a ListItem using the JavaScript SDK

                                                                    Use mutate for more fine-grained control

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

                                                                    Example 5
                                                                          
                                                                          
                                                                          
                                                                          Note: There are two separate events for list item adds and list item updates:

                                                                          Subscribe to a ListItem update with the JavaScript SDK

                                                                          Note: There are two separate events for list item adds and list item updates:

                                                                          Delete a ListItem resource

                                                                          delete
                                                                          https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
                                                                          Parameters
                                                                          Parameters in REST API format
                                                                          service_sid
                                                                          Path
                                                                          delete sid_like<IS> Not PII

                                                                          The SID of the Sync Service with the Sync List Item resource to delete.

                                                                          list_sid
                                                                          Path
                                                                          delete sid_like<ES> Not PII

                                                                          The SID of the Sync List with the Sync List Item resource to delete. Can be the Sync List resource's sid or its unique_name.

                                                                          index
                                                                          Path
                                                                          delete integer Not PII

                                                                          The index of the Sync List Item resource to delete.

                                                                          if_match
                                                                          Header
                                                                          delete string Not PII

                                                                          If provided, applies this mutation if (and only if) the “revision” field of this [map item] matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header.

                                                                          Example 1
                                                                                
                                                                                
                                                                                
                                                                                Deletes the 0-indexed item in the Sync List

                                                                                Delete a ListItem with the REST API

                                                                                Deletes the 0-indexed item in the Sync List
                                                                                Example 2
                                                                                      
                                                                                      
                                                                                      
                                                                                      Deletes the 0-index item in a Sync List

                                                                                      Delete a ListItem with the JavaScript SDK

                                                                                      Deletes the 0-index item in a Sync List
                                                                                      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