Skip to contentSkip to navigationSkip to topbar
Rate this Page:

ListItem resource


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

(information)

Info

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, when 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

listitem-properties page anchor
Resource properties
indextype: integerNot 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.


service_sidtype: SID<IS>Not PII

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


list_sidtype: SID<ES>Not PII

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


urltype: string<URI>Not PII

The absolute URL of the List Item resource.


revisiontype: stringNot PII

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


datatype: objectPII MTL: 7 days

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


date_expirestype: string<DATE TIME>Not PII

The date and time in GMT when the List Item expires and will be deleted, specified in ISO 8601(link takes you to an external page) 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_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 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

create-a-listitem-resource page anchor
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items

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 List Item in.


ListSidtype: stringNot PII
Path Parameter

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.


Request body parameters
Datatype: objectPII MTL: 7 days
Required

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


Ttltype: integerNot PII

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


ItemTtltype: integerNot PII

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


CollectionTtltype: integerNot PII

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

Create a ListItem with the REST API

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

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.syncLists('ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.syncListItems
_15
.create({data: {
_15
text: 'hello world',
_15
user: 'Charlies Xavier'
_15
}})
_15
.then(sync_list_item => console.log(sync_list_item.index));

Output

_16
{
_16
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"created_by": "created_by",
_16
"data": {
_16
"text": "hello world",
_16
"user": "Charlies Xavier"
_16
},
_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
"index": 100,
_16
"list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"revision": "revision",
_16
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/100"
_16
}

Push JSON into a list using the JavaScript SDK

push-json-into-a-list-using-the-javascript-sdk page anchor

_10
syncClient.list('example_list').then(function(list) {
_10
list.push({
_10
text: 'hello world',
_10
user: 'Charles Xavier'
_10
}).then(function(item) {
_10
console.log('Added: ', item.index);
_10
}).catch(function(err) {
_10
console.error(err);
_10
});
_10
});

Subscribe to a ListItem addition with the JavaScript SDK

subscribe-to-a-listitem-addition-with-the-javascript-sdk page anchor

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


_12
syncClient.list('example_list').then(function(list) {
_12
list.on('itemAdded', function(item) {
_12
console.log('index', item.index);
_12
console.log('JSON data', item.value);
_12
});
_12
_12
//Note that there are two separate events for list item adds and list item updates:
_12
list.on('itemUpdated', function(item) {
_12
console.log('index', item.index);
_12
console.log('JSON data', item.value);
_12
});
_12
});


Fetch a ListItem resource

fetch-a-listitem-resource page anchor
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

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


ListSidtype: stringNot PII
Path Parameter

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.


Indextype: integerNot PII
Path Parameter

The index of the Sync List Item resource to fetch.

Fetch a ListItem with the REST API

fetch-a-listitem-with-the-rest-api page anchor

Fetch only the first item

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_13
{
_13
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"created_by": "created_by",
_13
"data": {},
_13
"date_expires": "2015-07-30T21:00:00Z",
_13
"date_created": "2015-07-30T20:00:00Z",
_13
"date_updated": "2015-07-30T20:00:00Z",
_13
"index": ,
_13
"list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"revision": "revision",
_13
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/100"
_13
}

Fetch a ListItem with the JavaScript SDK

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

Fetch only the first item


_10
syncClient.list('example_list').then(function(list) {
_10
list.get(0).then(function(item) {
_10
console.log('show first item', item);
_10
});
_10
});


Read multiple ListItem resources

read-multiple-listitem-resources page anchor
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items

Retrieve all items belonging to a List.

(information)

Info

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.

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

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


ListSidtype: stringNot PII
Path Parameter

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


Ordertype: enum<STRING>Not PII
Query Parameter

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

Possible values:
ascdesc

Fromtype: stringNot PII
Query Parameter

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


Boundstype: enum<STRING>Not PII
Query Parameter

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.

Possible values:
inclusiveexclusive

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.

Get ListItems using the REST API

get-listitems-using-the-rest-api page anchor

Get 20 items from a SyncList

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_12
{
_12
"items": [],
_12
"meta": {
_12
"first_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_12
"key": "items",
_12
"next_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=1",
_12
"page": 0,
_12
"page_size": 50,
_12
"previous_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_12
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"
_12
}
_12
}

Get ListItems using the JavaScript SDK

get-listitems-using-the-javascript-sdk page anchor

Display the first item only


_10
syncClient.list('example_list').then(function(list) {
_10
list.getItems().then(function(page) {
_10
console.log('show first item', page.items[0]);
_10
});
_10
});


Update a ListItem resource

update-a-listitem-resource page anchor
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

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


ListSidtype: stringNot PII
Path Parameter

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.


Indextype: integerNot PII
Path Parameter

The index of the Sync List Item resource to update.


If-Matchtype: stringNot PII
Header Parameter

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(link takes you to an external page).


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


Ttltype: integerNot PII

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


ItemTtltype: integerNot PII

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


CollectionTtltype: integerNot PII

How long, in seconds(link takes you to an external page), 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.

Update a ListItem with the REST API

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

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

Output

_15
{
_15
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_15
"created_by": "created_by",
_15
"data": {
_15
"user": "Wolverine"
_15
},
_15
"date_expires": "2015-07-30T21:00:00Z",
_15
"date_created": "2015-07-30T20:00:00Z",
_15
"date_updated": "2015-07-30T20:00:00Z",
_15
"index": ,
_15
"list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_15
"revision": "revision",
_15
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_15
"url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Lists/ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/100"
_15
}

Change data in a single ListItem with the JavaScript SDK

change-data-in-a-single-listitem-with-the-javascript-sdk page anchor

Use the set method to change the data in a ListItem


_10
syncClient.list('example_list').then(function (list) {
_10
var newValue = {
_10
text: 'hello world',
_10
user: 'Wolverine'
_10
};
_10
list.set(0, newValue).then(function(item) {
_10
console.log('updated first item', item);
_10
});
_10
});

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

Update data in a ListItem with the JavaScript SDK

update-data-in-a-listitem-with-the-javascript-sdk page anchor

Use the update method to change data in a ListItem.


_10
syncClient.list('example-list').then(function(list) {
_10
list.update(0,{user: "Magneto"});
_10
});

Mutate data in a ListItem using the JavaScript SDK

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

Use mutate for more fine-grained control


_10
syncClient.list('example-list').then(function (list) {
_10
list.mutate(0,function(remoteData) {
_10
remoteData.user = "Cyclops";
_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.

Subscribe to a ListItem update with the JavaScript SDK

subscribe-to-a-listitem-update-with-the-javascript-sdk page anchor

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


_12
syncClient.list('example_list').then(function(list) {
_12
list.on('itemAdded', function(item) {
_12
console.log('index', item.index);
_12
console.log('JSON data', item.value);
_12
});
_12
_12
//Note that there are two separate events for list item adds and list item updates:
_12
list.on('itemUpdated', function(item) {
_12
console.log('index', item.index);
_12
console.log('JSON data', item.value);
_12
});
_12
});


Delete a ListItem resource

delete-a-listitem-resource page anchor
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Lists/{ListSid}/Items/{Index}

URI parameters
ServiceSidtype: stringNot PII
Path Parameter

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


ListSidtype: stringNot PII
Path Parameter

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.


Indextype: integerNot PII
Path Parameter

The index of the Sync List Item resource to delete.


If-Matchtype: stringNot PII
Header Parameter

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(link takes you to an external page).

Delete a ListItem with the REST API

delete-a-listitem-with-the-rest-api page anchor

Deletes the 0-indexed item in the Sync List

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
.syncLists('ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.syncListItems()
_11
.remove();

Delete a ListItem with the JavaScript SDK

delete-a-listitem-with-the-javascript-sdk page anchor

Deletes the 0-index item in a Sync List


_10
syncClient.list('example_list').then(function(list) {
_10
list.remove(0).then(function() {
_10
console.log('deleted first item');
_10
});
_10
});


Rate this Page: