Skip to contentSkip to navigationSkip to topbar
Rate this page:
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 nameTypePIIDescription
keystring
PII MTL: 30 days

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


account_sidSID<AC>
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

service_sidSID<IS>

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

map_sidSID<MP>

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>

The absolute URL of the Map Item resource.


revisionstring

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


dataobject

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


date_expiresstring<date-time>

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.


date_createdstring<date-time>

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>

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_bystring

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
ServiceSidstringrequired

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


MapSidstringrequired

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.

Property nameTypeRequiredPIIDescription
Keystringrequired

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


Dataobjectrequired

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


TtlintegerOptional

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


ItemTtlintegerOptional

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


CollectionTtlintegerOptional

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 API

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

_22
// Download the helper library from https://www.twilio.com/docs/node/install
_22
import twilio from "twilio";
_22
_22
// Find your Account SID and Auth Token at twilio.com/console
_22
// and set the environment variables. See http://twil.io/secure
_22
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22
const authToken = process.env.TWILIO_AUTH_TOKEN;
_22
const client = twilio(accountSid, authToken);
_22
_22
const syncMapItem = await client.sync.v1
_22
.services("ServiceSid")
_22
.syncMaps("MapSid")
_22
.syncMapItems.create({
_22
data: {
_22
name: "Foo Bar",
_22
level: 30,
_22
username: "foo_bar",
_22
},
_22
key: "foo",
_22
});
_22
_22
console.log(syncMapItem.key);

Output

_13
{
_13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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
"key": "foo",
_13
"map_sid": "MapSid",
_13
"revision": "revision",
_13
"service_sid": "ServiceSid",
_13
"url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"
_13
}

Use the set method


_10
syncClient.map('users').then(function(map) {
_10
map.set('Taylor', {
_10
phone_number: 12345678,
_10
country: 'UK'
_10
}).then(function(item) {
_10
console.log('Added: ', item.key);
_10
}).catch(function(err) {
_10
console.error(err);
_10
});
_10
});

Please 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:


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


Fetch a MapItem resource

fetch-a-mapitem-resource page anchor
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}

Property nameTypeRequiredPIIDescription
ServiceSidstringrequired

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


MapSidstringrequired

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.


Keystringrequired

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

Fetch a MapItem with the REST API

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

Request a MapItem by the key you defined when you created the item

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

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const syncMapItem = await client.sync.v1
_16
.services("ServiceSid")
_16
.syncMaps("MapSid")
_16
.syncMapItems("foo")
_16
.fetch();
_16
_16
console.log(syncMapItem.key);

Output

_13
{
_13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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
"key": "foo",
_13
"map_sid": "MapSid",
_13
"revision": "revision",
_13
"service_sid": "ServiceSid",
_13
"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


_10
syncClient.map('users').then(function(map) {
_10
map.get('Taylor').then(function(item) {
_10
console.log(item.value);
_10
});
_10
});


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.

Property nameTypeRequiredPIIDescription
ServiceSidstringrequired

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


MapSidstringrequired

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.

Property nameTypeRequiredPIIDescription
Orderenum<string>Optional

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

FromstringOptional

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


Boundsenum<string>Optional

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

PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Read all MapItems with the REST API

read-all-mapitems-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
import twilio from "twilio";
_15
_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 = twilio(accountSid, authToken);
_15
_15
const syncMapItems = await client.sync.v1
_15
.services("ServiceSid")
_15
.syncMaps("MapSid")
_15
.syncMapItems.list({ limit: 20 });
_15
_15
syncMapItems.forEach((s) => console.log(s.key));

Output

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

Read: Query a Map with filters with the REST API

read-query-a-map-with-filters-with-the-rest-api page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
const syncMapItems = await client.sync.v1
_19
.services("ServiceSid")
_19
.syncMaps("MapSid")
_19
.syncMapItems.list({
_19
from: "foo",
_19
order: "asc",
_19
limit: 20,
_19
});
_19
_19
syncMapItems.forEach((s) => console.log(s.key));

Output

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

Get all MapItems with the JavaScript SDK

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

This code sample displays the first item.


_10
syncClient.map('users').then(function(map) {
_10
map.getItems().then(function(page) {
_10
console.log('show first item', page.items[0].key,
_10
page.items[0].value);
_10
});
_10
});


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.

Property nameTypeRequiredPIIDescription
If-MatchstringOptional

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

Property nameTypeRequiredPIIDescription
ServiceSidstringrequired

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


MapSidstringrequired

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.


Keystringrequired

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

Property nameTypeRequiredPIIDescription
DataobjectOptional

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


TtlintegerOptional

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


ItemTtlintegerOptional

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


CollectionTtlintegerOptional

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 API

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

_22
// Download the helper library from https://www.twilio.com/docs/node/install
_22
import twilio from "twilio";
_22
_22
// Find your Account SID and Auth Token at twilio.com/console
_22
// and set the environment variables. See http://twil.io/secure
_22
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22
const authToken = process.env.TWILIO_AUTH_TOKEN;
_22
const client = twilio(accountSid, authToken);
_22
_22
const syncMapItem = await client.sync.v1
_22
.services("ServiceSid")
_22
.syncMaps("MapSid")
_22
.syncMapItems("foo")
_22
.update({
_22
data: {
_22
name: "FooBaz",
_22
level: 31,
_22
username: "foo_baz",
_22
},
_22
});
_22
_22
console.log(syncMapItem.key);

Output

_13
{
_13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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
"key": "foo",
_13
"map_sid": "MapSid",
_13
"revision": "revision",
_13
"service_sid": "ServiceSid",
_13
"url": "https://sync.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Maps/MPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Items/key"
_13
}

Update: Update a MapItem with Conflict Resolution with the REST API

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

_22
// Download the helper library from https://www.twilio.com/docs/node/install
_22
import twilio from "twilio";
_22
_22
// Find your Account SID and Auth Token at twilio.com/console
_22
// and set the environment variables. See http://twil.io/secure
_22
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22
const authToken = process.env.TWILIO_AUTH_TOKEN;
_22
const client = twilio(accountSid, authToken);
_22
_22
const syncMapItem = await client.sync.v1
_22
.services("ServiceSid")
_22
.syncMaps("MapSid")
_22
.syncMapItems("foo")
_22
.update({
_22
data: {
_22
name: "FooBaz",
_22
level: 31,
_22
username: "foo_baz",
_22
},
_22
});
_22
_22
console.log(syncMapItem.revision);

Output

_13
{
_13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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
"key": "foo",
_13
"map_sid": "MapSid",
_13
"revision": "revision",
_13
"service_sid": "ServiceSid",
_13
"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


_10
syncClient.map('users').then(function(map) {
_10
map.update('Taylor',{country: "IRL"});
_10
});

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.


_10
syncClient.map('users').then(function (map) {
_10
map.mutate('david',function(remoteData) {
_10
remoteData.country = "USA";
_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 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:


_12
syncClient.map('users').then(function (map) {
_12
map.on('itemAdded', function(item) {
_12
console.log('key', item.key);
_12
console.log('JSON data', item.value);
_12
});
_12
_12
//Note that there are two separate events for map item adds and map item updates:
_12
map.on('itemUpdated', function(item) {
_12
console.log('key', item.key);
_12
console.log('JSON data', item.value);
_12
});
_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.

Property nameTypeRequiredPIIDescription
If-MatchstringOptional

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

Property nameTypeRequiredPIIDescription
ServiceSidstringrequired

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


MapSidstringrequired

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.


Keystringrequired

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

Delete a MapItem with the REST API

delete-a-mapitem-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
import twilio from "twilio";
_14
_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 = twilio(accountSid, authToken);
_14
_14
await client.sync.v1
_14
.services("ServiceSid")
_14
.syncMaps("MapSid")
_14
.syncMapItems("foo")
_14
.remove();

Delete: Delete a MapItem with Conflict Resolution using the REST API

delete-delete-a-mapitem-with-conflict-resolution-using-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
import twilio from "twilio";
_14
_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 = twilio(accountSid, authToken);
_14
_14
await client.sync.v1
_14
.services("ServiceSid")
_14
.syncMaps("MapSid")
_14
.syncMapItems("foo")
_14
.remove();

Delete a single MapItem with the JavaScript SDK

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

Deletes the item with key 'Taylor'


_10
syncClient.map('users').then(function(map) {
_10
map.remove('Taylor').then(function() {
_10
console.log('item deleted');
_10
});
_10
});


Rate this page: