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
|
The automatically generated index of the List Item. The |
account_sid
|
The SID of the Account that created the List Item resource. |
service_sid
|
The SID of the Sync Service the resource is associated with. |
list_sid
|
The SID of the Sync List that contains the List Item. |
url
|
The absolute URL of the List Item resource. |
revision
|
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
|
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 |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
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 |
Create a ListItem resource
https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the Sync Service to create the new List Item in. |
list_sid
Path
|
The SID of the Sync List to add the new List Item to. Can be the Sync List resource's |
data
Required
|
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
|
An alias for |
item_ttl
Optional
|
How long, in seconds, before the List Item expires (time-to-live) and is deleted. |
collection_ttl
Optional
|
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
Fetch a ListItem resource
https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the Sync Service with the Sync List Item resource to fetch. |
list_sid
Path
|
The SID of the Sync List with the Sync List Item resource to fetch. Can be the Sync List resource's |
index
Path
|
The index of the Sync List Item resource to fetch. |
Example 1
Example 2
Read multiple ListItem resources
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
|
The SID of the Sync Service with the List Item resources to read. |
list_sid
Path
|
The SID of the Sync List with the List Items to read. Can be the Sync List resource's |
order
Optional
|
How to order the List Items returned by their |
from
Optional
|
The |
bounds
Optional
|
Whether to include the List Item referenced by the |
Example 1
Example 2
Update a ListItem resource
https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the Sync Service with the Sync List Item resource to update. |
list_sid
Path
|
The SID of the Sync List with the Sync List Item resource to update. Can be the Sync List resource's |
index
Path
|
The index of the Sync List Item resource to update. |
data
Optional
|
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
|
An alias for |
item_ttl
Optional
|
How long, in seconds, before the List Item expires (time-to-live) and is deleted. |
collection_ttl
Optional
|
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 |
if_match
Header
|
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
Please note: Using set will overwrite any existing data in a list item.
Example 3
Example 4
The mutate function helps your Javascript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.
Example 5
Delete a ListItem resource
https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the Sync Service with the Sync List Item resource to delete. |
list_sid
Path
|
The SID of the Sync List with the Sync List Item resource to delete. Can be the Sync List resource's |
index
Path
|
The index of the Sync List Item resource to delete. |
if_match
Header
|
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
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 Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
