Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sync REST: Maps

A map is an unordered collection of individual items, addressable by a key that you define.

  • Items can be inserted, updated, removed and iterated.
  • Each item is limited to 16KB of data minus small internal overhead.
  • Item read or update access is performed using item key that is provided by you as an arbitrary string (up to 256 characters).
  • Full map modification history is maintained with every change triggering new revision.
  • Strict ordering of map mutation events is guaranteed, but the map item ordering is not defined.
  • Expires and gets deleted automatically, if eviction is configured via TTL parameter. By default, data is persisted permanently.

Map Root Properties

Each Map object root resource has the following properties. Unique name and expiration date attributes are optional and allowed to be null.

account_sid
sid<AC> Not PII

The unique SID identifier of the Twilio Account.

created_by

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

date_created
date_time<iso8601> Not PII

The date this Map was created, given in UTC ISO 8601 format.

date_expires
date_time<iso8601> Not PII

Contains the date this Map expires and gets deleted automatically. Contains null if the Map persists permanently.

date_updated
date_time<iso8601> Not PII

Specifies the date this Map was last updated, given in UTC ISO 8601 format.

links
uri_map Not PII

A dictionary of URL links to nested resources of this Map.

revision
string Not PII

Contains the current revision of this Map, represented by a string identifier.

service_sid
sid<IS> Not PII

The unique SID identifier of the Service Instance that hosts this Map object.

sid
sid<MP> Not PII

The unique 34-character SID identifier of the Map.

unique_name

The unique and addressable name of this Map. Optional, up to 256 characters long.

url
url Not PII

The absolute URL for this Map.

Example

{
  "account_sid": "ACxx",
  "service_sid": "ISxx",
  "sid": "MPxx",
  "unique_name": "MyMap",
  "revision": "1a",
  "date_created": "2015-11-24T22:18:57Z",
  "date_updated": "2015-11-24T22:18:57Z",
  "date_expires": null,
  "created_by": "system",
  "url": "https://sync.twilio.com/v1/Services/ISxx/Maps/MPxx",
  "links": {
    "items": "https://sync.twilio.com/v1/Services/ISxx/Maps/MPxx/Items",
    "permissions": "https://sync.twilio.com/v1/Services/ISxx/Maps/MPxx/Permissions"
  }
}

Map Item Properties

Each Map Item resource is nested under the parent Map root resource and has the following properties.

account_sid
sid<AC> Not PII

The unique SID identifier of the Twilio Account.

created_by

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

data

Contains arbitrary user-defined, schema-less data that this Map Item stores, represented by a JSON object, up to 16KB.

date_created
date_time<iso8601> Not PII

The date this Map was created, given in UTC ISO 8601 format.

date_expires
date_time<iso8601> Not PII

Contains the date this Map expires and gets deleted automatically. Contains null if the Map persists permanently.

date_updated
date_time<iso8601> Not PII

Specifies the date this Map was last updated, given in UTC ISO 8601 format.

key

The unique user-defined key of this Map Item. Up to 256 characters long.

map_sid
sid<MP> Not PII

The unique 34-character SID identifier of the Map containing this Item.

revision
string Not PII

Contains the current revision of this Map, represented by a string identifier.

service_sid
sid<IS> Not PII

The unique SID identifier of the Service Instance that hosts this Map object.

url
url Not PII

The absolute URL for this Map.

Example

{
  "account_sid": "ACxx",
  "service_sid": "ISxx",
  "map_sid": "MPxx",
  "key": "MyKey",
  "revision": "1b",
  "date_created": "2015-11-24T22:19:58Z",
  "date_updated": "2015-11-24T22:19:58Z",
  "date_expires": null,
  "created_by": "system",
  "url": "https://sync.twilio.com/v1/Services/ISxx/Maps/MPxx/Items/MyKey",
  "data": {
      <user-defined Map Item content>
  }
}

Actions


List All Maps

GET /v1/Services/ISxx/Maps

Retrieve a list of all Maps belonging to this Service Instance.

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

Example

Loading Code Sample...
      
      
          
          
          
          
        

      Create a Map

      POST /v1/Services/ISxx/Maps
      

      Create a new Map in this Service Instance, optionally giving it a unique name and assigning an expiration deadline.

      Parameters

      Ttl
      Optional
      post integer Not PII

      Time-to-live of this Map in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

      UniqueName
      Optional
      post string Not PII

      Human-readable name for this map

      Loading Code Sample...
          
          
              
              
              
              
            

          Retrieve a Map

          GET /v1/Services/ISxx/Maps/MPxx|UniqueName
          

          Fetch information about a specific Map by its SID or unique name.

          Example

          Loading Code Sample...
              
              
                  
                  
                  
                  
                

              Update a Map

              POST /v1/Services/ISxx/Maps/MPxx|UniqueName
              

              Update the Map expiration deadline, addressed by its SID or unique name.

              Parameters

              Ttl
              Optional
              post integer Not PII

              New time-to-live of this Map in seconds. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    

                  Add Item to Map

                  POST /v1/Services/ISxx/Maps/MPxx|UniqueName/Items
                  

                  Insert a new item into this Map, supplying its payload, and optionally providing an item expiration deadline.

                  Parameters

                  Data
                  Required
                  post object Not PII

                  Contains arbitrary user-defined, schema-less data that this Map Item stores, represented by a JSON object, up to 16KB.

                  Key
                  Required
                  post string Not PII

                  The unique user-defined key of this Map Item. Up to 256 characters long.

                  Ttl
                  Optional
                  post integer Not PII

                  Time-to-live of this Map in seconds, defaults to no expiration. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        

                      Get Item From Map

                      GET /v1/Services/ISxx/Maps/MPxx|UniqueName/Items/<KEY>
                      

                      Fetch data of a specific item in the current Map, addressed by Map SID (or unique name) and item key.

                      Example

                      Loading Code Sample...
                          
                          
                              
                              
                              
                              
                            

                          Query Items From Map

                          GET /v1/Services/ISxx/Maps/MPxx|UniqueName/Items
                          

                          Retrieve a list of all items belonging to this Map.

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

                          Parameters

                          From
                          Optional
                          get string Not PII

                          The Item key offset (including the specified key). If not present, query is performed from the start or end, depending on the Order query parameter.

                          Order
                          Optional
                          get enum:query_result_order Not PII

                          A string; asc or desc. Map Items are ordered lexicographically by Item key.

                          Loading Code Sample...
                              
                              
                                  
                                  
                                  
                                  
                                

                              Update Item In a Map

                              POST /v1/Services/ISxx/Maps/MPxx|UniqueName/Items/<KEY>
                              

                              Update data and/or expiration deadline of a specific item in the current Map, addressed by SID (or unique name) and item key.

                              Parameters

                              Data
                              Optional
                              post object Not PII

                              Contains an arbitrary JSON object to be stored in this Map Item. Serialized to string to respect HTTP form input, up to 16KB.

                              Ttl
                              Optional
                              post integer Not PII

                              New time-to-live of this Map in seconds. In the range [1, 31 536 000 (1 year)], or 0 for infinity.

                              Loading Code Sample...
                                  
                                  
                                      
                                      
                                      
                                      
                                    

                                  Remove Item From Map

                                  DELETE /v1/Services/ISxx/Maps/MPxx|UniqueName/Items/<KEY>
                                  

                                  Permanently delete a specific item from the current Map, addressed by SID (or unique name) and item key.

                                  Example

                                  Loading Code Sample...
                                      
                                      
                                          
                                          
                                          
                                          
                                        

                                      Delete a Map

                                      DELETE /v1/Services/ISxx/Maps/MPxx|UniqueName
                                      

                                      Permanently delete a specific Map along with all items belonging to it from current Service Instance, addressed by SID or unique name.

                                      Example

                                      Loading Code Sample...
                                          
                                          
                                              
                                              
                                              
                                              
                                            

                                          Need some help?

                                          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                                          Loading Code Sample...