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 .
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
Resource properties The unique, user-defined key for the Map Item.
The SID of the Sync Map that contains the Map Item.
The absolute URL of the Map Item resource.
The current revision of the Map Item, represented as a string.
An arbitrary, schema-less object that the Map Item stores. Can be up to 16 KiB in length.
date_expires
type: string<DATE TIME> Not PIIThe 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_created
type: string<DATE TIME> Not PIIdate_updated
type: string<DATE TIME> Not PIIThe 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
.
POST https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items
URI parameters Path Parameter
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 Required
The unique, user-defined key for the Map Item. Can be up to 320 characters long.
Required
A JSON string that represents an arbitrary, schema-less object that the Map Item stores. Can be up to 16 KiB in length.
An alias for item_ttl
. If both parameters are provided, this value is ignored.
_16 // Download the helper library from https://www.twilio.com/docs/node/install
_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 = require('twilio')(accountSid, authToken);
_16 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .create({key: 'foo', data: {
_16 .then(sync_map_item => console.log(sync_map_item.key));
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "created_by": "created_by",
_17 "username": "foo_bar"
_17 "date_expires": "2015-07-30T21:00:00Z",
_17 "date_created": "2015-07-30T20:00:00Z",
_17 "date_updated": "2015-07-30T20:00:00Z",
_17 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "revision": "revision",
_17 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
Use the set method
_10 syncClient.map('users').then(function(map) {
_10 phone_number: 12345678,
_10 }).then(function(item) {
_10 console.log('Added: ', item.key);
_10 }).catch(function(err) {
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.
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 //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);
GET https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}
URI parameters Path Parameter
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
.
Path Parameter
The key
value of the Sync Map Item resource to fetch.
Request a MapItem by the key you defined when you created the item
_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 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .then(sync_map_item => console.log(sync_map_item.key));
_13 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13 "created_by": "created_by",
_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 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13 "revision": "revision",
_13 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
Fetches by a specific key
_10 syncClient.map('users').then(function(map) {
_10 map.get('Taylor').then(function(item) {
_10 console.log(item.value);
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.
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.
URI parameters Path Parameter
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 Parameter
The key
of the first Sync Map Item resource to read. See also bounds
.
Query Parameter
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:
inclusive
exclusive
Query Parameter
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Query Parameter
The page index. This value is simply for client state.
Query Parameter
The page token. This is provided by the API.
_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 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .then(syncMapItems => syncMapItems.forEach(s => console.log(s.key)));
_26 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "created_by": "created_by",
_26 "date_expires": "2015-07-30T21:00:00Z",
_26 "date_created": "2015-07-30T20:00:00Z",
_26 "date_updated": "2015-07-30T20:00:00Z",
_26 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "revision": "revision",
_26 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
_26 "first_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_26 "next_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=1",
_26 "previous_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_26 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"
_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 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12 .list({from: 'foo', order: 'asc', limit: 20})
_12 .then(syncMapItems => syncMapItems.forEach(s => console.log(s.key)));
_26 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "created_by": "created_by",
_26 "date_expires": "2015-07-30T21:00:00Z",
_26 "date_created": "2015-07-30T20:00:00Z",
_26 "date_updated": "2015-07-30T20:00:00Z",
_26 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "revision": "revision",
_26 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
_26 "first_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_26 "next_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=1",
_26 "previous_page_url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0",
_26 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items?From=from&Bounds=inclusive&Order=asc&PageSize=50&Page=0"
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);
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.
Request headers URI parameters Path Parameter
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
.
Path Parameter
The key
value of the Sync Map Item resource to update.
Request body parameters A JSON string that represents an arbitrary, schema-less object that the Map Item stores. Can be up to 16 KiB in length.
An alias for item_ttl
. If both parameters are provided, this value is ignored.
How long, in seconds(link takes you to an external page) , 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.
_16 // Download the helper library from https://www.twilio.com/docs/node/install
_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 = require('twilio')(accountSid, authToken);
_16 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .then(sync_map_item => console.log(sync_map_item.key));
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "created_by": "created_by",
_17 "username": "foo_baz"
_17 "date_expires": "2015-07-30T21:00:00Z",
_17 "date_created": "2015-07-30T20:00:00Z",
_17 "date_updated": "2015-07-30T20:00:00Z",
_17 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "revision": "revision",
_17 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
_16 // Download the helper library from https://www.twilio.com/docs/node/install
_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 = require('twilio')(accountSid, authToken);
_16 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_16 .then(sync_map_item => console.log(sync_map_item.revision));
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "created_by": "created_by",
_17 "username": "foo_baz"
_17 "date_expires": "2015-07-30T21:00:00Z",
_17 "date_created": "2015-07-30T20:00:00Z",
_17 "date_updated": "2015-07-30T20:00:00Z",
_17 "map_sid": "MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "revision": "revision",
_17 "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "url": "https://sync.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Maps/MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Items/key"
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"});
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";
The mutate
function helps your Javascript code respond to concurrent updates with versioned control. See the corresponding JavaScript SDK documentation for details.
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 //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);
DELETE https://sync.twilio.com/v1/Services/{ServiceSid}/Maps/{MapSid}/Items/{Key}
Permanently delete a specific item from an existing Map.
Request headers URI parameters Path Parameter
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
.
Path Parameter
The key
value of the Sync Map Item resource to delete.
_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 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_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 client.sync.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .syncMaps('MPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .remove({ifMatch: '1a'});
Deletes the item with key 'Taylor'
_10 syncClient.map('users').then(function(map) {
_10 map.remove('Taylor').then(function() {
_10 console.log('item deleted');