Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Sync MapItem Resource

A Sync MapItem is an individual item that belongs to one or more of your Sync Maps. See the full API reference documentation for the Sync Map resource here.

(information)

Info

You need to create a Map first before you can use this resource to create, read, update, and delete items.

Sync MapItems:

  • can be inserted, updated, removed and iterated
  • are limited to 16KB of data

Sync MapItem properties

sync-mapitem-properties page anchor
Property nameTypeRequiredDescriptionChild properties
keystring

Optional

PII MTL: 30 days

The unique, user-defined key for the Map Item.

accountSidSID<AC>

Optional

Not PII

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

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
serviceSidSID<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
mapSidSID<MP>

Optional

Not PII

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

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

Optional

Not PII

The absolute URL of the Map Item resource.

revisionstring

Optional

Not PII

The current revision of the Map Item, represented as a string.

dataobject

Optional

PII MTL: 7 days

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

dateExpiresstring<date-time>

Optional

Not PII

The date and time in GMT when the Map Item expires and will be deleted, specified in ISO 8601(link takes you to an external page) format. If the Map Item does not expire, this value is null. The Map Item might not be deleted immediately after it expires.

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

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

createdBystring

Optional

PII MTL: 30 days

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

Create a MapItem resource

create-a-mapitem-resource page anchor

POST https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
serviceSidstring
required
Not PII

The SID of the Sync Service to create the Map Item in.

mapSidstring
required
Not PII

The SID of the Sync Map to add the new Map Item to. Can be the Sync Map 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
keystring
required
PII MTL: 30 days

The unique, user-defined key for the Map Item. Can be up to 320 characters long.

dataobject
required
PII MTL: 7 days

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

ttlinteger

Optional

Not PII

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

itemTtlinteger

Optional

Not PII

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

collectionTtlinteger

Optional

Not PII

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

Create a MapItem with the REST APILink to code sample: Create a MapItem 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 createSyncMapItem() {

11
  const syncMapItem = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems.create({

15
      data: {

16
        name: "Foo Bar",

17
        level: 30,

18
        username: "foo_bar",

19
      },

20
      key: "foo",

21
    });

22


23
  console.log(syncMapItem.key);

24
}

25


26
createSyncMapItem();

Response

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
  "key": "foo",

9
  "map_sid": "MapSid",

10
  "revision": "revision",

11
  "service_sid": "ServiceSid",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"

13
}

Add JSON to a Map

add-json-to-a-map page anchor

Use the set method

1
syncClient.map("users").then(function (map) {

2
  map

3
    .set("Taylor", {

4
      phone_number: 12345678,

5
      country: "UK",

6
    })

7
    .then(function (item) {

8
      console.log("Added: ", item.key);

9
    })

10
    .catch(function (err) {

11
      console.error(err);

12
    });

13
});

Note: You can also use the set method to update data in existing JSON data in a Map. However, using set will overwrite any existing data in a MapItem.

Subscribe to a MapItem addition with the JavaScript SDK

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

Note that there are two separate events for map item adds and map item updates:

1
syncClient.map("users").then(function (map) {

2
  map.on("itemAdded", function (item) {

3
    console.log("key", item.key);

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

5
  });

6


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

8
  map.on("itemUpdated", function (item) {

9
    console.log("key", item.key);

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

11
  });

12
});

Fetch a MapItem resource

fetch-a-mapitem-resource page anchor

GET https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
serviceSidstring
required
Not PII

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

mapSidstring
required
Not PII

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

keystring
required
PII MTL: 30 days

The key value of the Sync Map Item resource to fetch.

Fetch a MapItem with the REST APILink to code sample: Fetch a MapItem 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 fetchSyncMapItem() {

11
  const syncMapItem = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems("foo")

15
    .fetch();

16


17
  console.log(syncMapItem.key);

18
}

19


20
fetchSyncMapItem();

Response

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
  "key": "foo",

9
  "map_sid": "MapSid",

10
  "revision": "revision",

11
  "service_sid": "ServiceSid",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"

13
}

Fetch a single MapItem with the JavaScript SDK

fetch-a-single-mapitem-with-the-javascript-sdk page anchor

Fetches by a specific key

1
syncClient.map("users").then(function (map) {

2
  map.get("Taylor").then(function (item) {

3
    console.log(item.value);

4
  });

5
});

Read all MapItem resources

read-all-mapitem-resources page anchor

GET https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items

MapItem read access is performed using the key that provided as an arbitrary string to identify the item.

(information)

Info

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

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
serviceSidstring
required
Not PII

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

mapSidstring
required
Not PII

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
orderenum<string>

Optional

Not PII

How to order the Map Items returned by their key value. Can be: asc (ascending) or desc (descending) and the default is ascending. Map Items are ordered lexicographically(link takes you to an external page) by Item key.

Possible values:
ascdesc
fromstring

Optional

Not PII

The key of the first Sync Map Item resource to read. See also bounds.

boundsenum<string>

Optional

Not PII

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

Possible values:
inclusiveexclusive
pageSizeinteger<int64>

Optional

Not PII

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

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

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

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Read all MapItems with the REST APILink to code sample: Read all MapItems 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 listSyncMapItem() {

11
  const syncMapItems = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

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

15


16
  syncMapItems.forEach((s) => console.log(s.key));

17
}

18


19
listSyncMapItem();

Response

1
{

2
  "items": [],

3
  "meta": {

4
    "first_page_url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/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/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"

11
  }

12
}
Read: Query a Map with filters with the REST APILink to code sample: Read: Query a Map with filters 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 listSyncMapItem() {

11
  const syncMapItems = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems.list({

15
      from: "foo",

16
      order: "asc",

17
      limit: 20,

18
    });

19


20
  syncMapItems.forEach((s) => console.log(s.key));

21
}

22


23
listSyncMapItem();

Response

1
{

2
  "items": [],

3
  "meta": {

4
    "first_page_url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/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/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"

11
  }

12
}

Get all MapItems with the JavaScript SDK

get-all-mapitems-with-the-javascript-sdk page anchor

This code sample displays the first item.

1
syncClient.map("users").then(function (map) {

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

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

4
  });

5
});

Update a MapItem resource

update-a-mapitem-resource page anchor

POST https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}

MapItem update access is performed using the key that provided as an arbitrary string to identify the item.

Headers

headers page anchor
Property nameTypeRequiredPIIDescription
ifMatchstring

Optional

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
serviceSidstring
required
Not PII

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

mapSidstring
required
Not PII

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

keystring
required
PII MTL: 30 days

The key value of the Sync Map Item resource to update.

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
dataobject

Optional

PII MTL: 7 days

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

ttlinteger

Optional

Not PII

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

itemTtlinteger

Optional

Not PII

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

collectionTtlinteger

Optional

Not PII

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

Update a MapItem with the REST APILink to code sample: Update a MapItem 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 updateSyncMapItem() {

11
  const syncMapItem = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems("foo")

15
    .update({

16
      data: {

17
        name: "FooBaz",

18
        level: 31,

19
        username: "foo_baz",

20
      },

21
    });

22


23
  console.log(syncMapItem.key);

24
}

25


26
updateSyncMapItem();

Response

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
  "key": "foo",

9
  "map_sid": "MapSid",

10
  "revision": "revision",

11
  "service_sid": "ServiceSid",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"

13
}
Update: Update a MapItem with Conflict Resolution with the REST APILink to code sample: Update: Update a MapItem with Conflict Resolution 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 updateSyncMapItem() {

11
  const syncMapItem = await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems("foo")

15
    .update({

16
      data: {

17
        name: "FooBaz",

18
        level: 31,

19
        username: "foo_baz",

20
      },

21
      ifMatch: "1a",

22
    });

23


24
  console.log(syncMapItem.revision);

25
}

26


27
updateSyncMapItem();

Response

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
  "key": "foo",

9
  "map_sid": "MapSid",

10
  "revision": "revision",

11
  "service_sid": "ServiceSid",

12
  "url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"

13
}

Update data in a MapItem with the JavaScript SDK

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

Use the update method to change the data in a Map Item

1
syncClient.map("users").then(function (map) {

2
  map.update("Taylor", { country: "IRL" });

3
});

Mutate data in a MapItem using the JavaScript SDK

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

Use mutate for more fine-grained control over updates.

1
syncClient.map("users").then(function (map) {

2
  map.mutate("david", function (remoteData) {

3
    remoteData.country = "USA";

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 MapItem update with the JavaScript SDK

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

Note that there are two separate events for map item adds and map item updates:

1
syncClient.map("users").then(function (map) {

2
  map.on("itemAdded", function (item) {

3
    console.log("key", item.key);

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

5
  });

6


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

8
  map.on("itemUpdated", function (item) {

9
    console.log("key", item.key);

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

11
  });

12
});

Delete a MapItem resource

delete-a-mapitem-resource page anchor

DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}

Permanently delete a specific item from an existing Map.

Headers

headers-1 page anchor
Property nameTypeRequiredPIIDescription
ifMatchstring

Optional

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
serviceSidstring
required
Not PII

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

mapSidstring
required
Not PII

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

keystring
required
Not PII

The key value of the Sync Map Item resource to delete.

Delete a MapItem with the REST APILink to code sample: Delete a MapItem 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 deleteSyncMapItem() {

11
  await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems("foo")

15
    .remove();

16
}

17


18
deleteSyncMapItem();
Delete: Delete a MapItem with Conflict Resolution using the REST APILink to code sample: Delete: Delete a MapItem with Conflict Resolution 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 deleteSyncMapItem() {

11
  await client.sync.v1

12
    .services("ServiceSid")

13
    .syncMaps("MapSid")

14
    .syncMapItems("foo")

15
    .remove({ ifMatch: "1a" });

16
}

17


18
deleteSyncMapItem();

Delete a single MapItem with the JavaScript SDK

delete-a-single-mapitem-with-the-javascript-sdk page anchor

Deletes the item with key 'Taylor'

1
syncClient.map("users").then(function (map) {

2
  map.remove("Taylor").then(function () {

3
    console.log("item deleted");

4
  });

5
});