Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On 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
Property nameTypeRequiredDescriptionChild properties
indexintegerOptional
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.

Default: 0
account_sidSID<AC>Optional
Not PII

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

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
service_sidSID<IS>Optional
Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
list_sidSID<ES>Optional
Not PII

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

Pattern: ^ES[0-9a-fA-F]{32}$Min length: 34Max length: 34
urlstring<uri>Optional
Not PII

The absolute URL of the List Item resource.

revisionstringOptional
Not PII

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

dataobjectOptional
PII MTL: 7 days

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

date_expiresstring<date-time>Optional
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_createdstring<date-time>Optional
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_updatedstring<date-time>Optional
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_bystringOptional
PII 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

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
ServiceSidstringrequired
Not PII

The SID of the Sync Service to create the new List Item in.

ListSidstringrequired
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.

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Dataobjectrequired
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.

TtlintegerOptional
Not PII

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

ItemTtlintegerOptional
Not PII

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

CollectionTtlintegerOptional
Not PII

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

Create a ListItem with the REST APILink to code sample: Create a ListItem with the REST API
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createSyncListItem() {

11
  const syncListItem = await client.sync.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .syncLists("ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .syncListItems.create({

15
      data: {

16
        text: "hello world",

17
        user: "Charlies Xavier",

18
      },

19
    });

20


21
  console.log(syncListItem.index);

22
}

23


24
createSyncListItem();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "created_by": "created_by",

4
  "data": {},

5
  "date_expires": "2015-07-30T21:00:00Z",

6
  "date_created": "2015-07-30T20:00:00Z",

7
  "date_updated": "2015-07-30T20:00:00Z",

8
  "index": 100,

9
  "list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

10
  "revision": "revision",

11
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists/ESaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/100"

13
}

Push JSON into a list using the JavaScript SDK

push-json-into-a-list-using-the-javascript-sdk page anchor
1
syncClient.list('example_list').then(function(list) {

2
  list.push({

3
    text: 'hello world',

4
    user: 'Charles Xavier'

5
  }).then(function(item) {

6
    console.log('Added: ', item.index);

7
  }).catch(function(err) {

8
    console.error(err);

9
  });

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:

1
syncClient.list('example_list').then(function(list) {

2
  list.on('itemAdded', function(item) {

3
    console.log('index', item.index);

4
    console.log('JSON data', item.value);

5
  });

6


7
//Note that there are two separate events for list item adds and list item updates:

8
  list.on('itemUpdated', function(item) {

9
    console.log('index', item.index);

10
    console.log('JSON data', item.value);

11
  });

12
});

Fetch a ListItem resource

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

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
ServiceSidstringrequired
Not PII

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

ListSidstringrequired
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.

Indexintegerrequired
Not PII

The index of the Sync List Item resource to fetch.

Fetch a ListItem with the REST APILink to code sample: Fetch a ListItem with the REST API
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchSyncListItem() {

11
  const syncListItem = await client.sync.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .syncLists("ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .syncListItems(42)

15
    .fetch();

16


17
  console.log(syncListItem.index);

18
}

19


20
fetchSyncListItem();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "created_by": "created_by",

4
  "data": {},

5
  "date_expires": "2015-07-30T21:00:00Z",

6
  "date_created": "2015-07-30T20:00:00Z",

7
  "date_updated": "2015-07-30T20:00:00Z",

8
  "index": 42,

9
  "list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

10
  "revision": "revision",

11
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists/ESaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/100"

13
}

Fetch a ListItem with the JavaScript SDK

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

Fetch only the first item

1
syncClient.list('example_list').then(function(list) {

2
  list.get(0).then(function(item) {

3
    console.log('show first item', item);

4
  });

5
});

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.

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
ServiceSidstringrequired
Not PII

The SID of the Sync Service with the List Item resources to read.

ListSidstringrequired
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.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
Orderenum<string>Optional
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.

Possible values:
ascdesc
FromstringOptional
Not PII

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

Boundsenum<string>Optional
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.

Possible values:
inclusiveexclusive
PageSizeintegerOptional
Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

The page index. This value is simply for client state.

Minimum: 0
PageTokenstringOptional
Not PII

The page token. This is provided by the API.

Get ListItems using the REST APILink to code sample: Get ListItems using the REST API
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listSyncListItem() {

11
  const syncListItems = await client.sync.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .syncLists("ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .syncListItems.list({ limit: 20 });

15


16
  syncListItems.forEach((s) => console.log(s.index));

17
}

18


19
listSyncListItem();

Output

1
{

2
  "items": [],

3
  "meta": {

4
    "first_page_url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists/ESaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",

5
    "key": "items",

6
    "next_page_url": null,

7
    "page": 0,

8
    "page_size": 50,

9
    "previous_page_url": null,

10
    "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists/ESaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"

11
  }

12
}

Get ListItems using the JavaScript SDK

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

Display the first item only

1
syncClient.list('example_list').then(function(list) {

2
  list.getItems().then(function(page) {

3
    console.log('show first item', page.items[0]);

4
  });

5
});

Update a ListItem resource

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

Headers

headers page anchor
Property nameTypeRequiredPIIDescription
If-MatchstringOptional
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(link takes you to an external page).

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
ServiceSidstringrequired
Not PII

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

ListSidstringrequired
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.

Indexintegerrequired
Not PII

The index of the Sync List Item resource to update.

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
DataobjectOptional
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.

TtlintegerOptional
Not PII

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

ItemTtlintegerOptional
Not PII

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

CollectionTtlintegerOptional
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.

Update a ListItem with the REST APILink to code sample: Update a ListItem with the REST API
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateSyncListItem() {

11
  const syncListItem = await client.sync.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .syncLists("ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .syncListItems(42)

15
    .update({

16
      data: {

17
        user: "Wolverine",

18
      },

19
    });

20


21
  console.log(syncListItem.index);

22
}

23


24
updateSyncListItem();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "created_by": "created_by",

4
  "data": {},

5
  "date_expires": "2015-07-30T21:00:00Z",

6
  "date_created": "2015-07-30T20:00:00Z",

7
  "date_updated": "2015-07-30T20:00:00Z",

8
  "index": 42,

9
  "list_sid": "ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

10
  "revision": "revision",

11
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Lists/ESaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/100"

13
}

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

1
syncClient.list('example_list').then(function (list) {

2
  var newValue = {

3
    text: 'hello world',

4
    user: 'Wolverine'

5
  };

6
  list.set(0, newValue).then(function(item) {

7
    console.log('updated first item', item);

8
  });

9
});

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.

1
syncClient.list('example-list').then(function(list) {

2
  list.update(0,{user: "Magneto"});

3
});

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

1
syncClient.list('example-list').then(function (list) {

2
  list.mutate(0,function(remoteData) {

3
    remoteData.user = "Cyclops";

4
    return remoteData;

5
  });

6
});

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:

1
syncClient.list('example_list').then(function(list) {

2
  list.on('itemAdded', function(item) {

3
    console.log('index', item.index);

4
    console.log('JSON data', item.value);

5
  });

6


7
//Note that there are two separate events for list item adds and list item updates:

8
  list.on('itemUpdated', function(item) {

9
    console.log('index', item.index);

10
    console.log('JSON data', item.value);

11
  });

12
});

Delete a ListItem resource

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

Headers

headers-1 page anchor
Property nameTypeRequiredPIIDescription
If-MatchstringOptional
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(link takes you to an external page).

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
ServiceSidstringrequired
Not PII

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

ListSidstringrequired
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.

Indexintegerrequired
Not PII

The index of the Sync List Item resource to delete.

Delete a ListItem with the REST APILink to code sample: Delete a ListItem with the REST API
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function deleteSyncListItem() {

11
  await client.sync.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .syncLists("ESXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .syncListItems(42)

15
    .remove();

16
}

17


18
deleteSyncListItem();

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

1
syncClient.list('example_list').then(function(list) {

2
  list.remove(0).then(function() {

3
    console.log('deleted first item');

4
  });

5
});

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.