The Map My Customers web services APIs allow for programmatic access to Map My Customers data. Use these REST APIs to retrieve information about your account, customer data, routes, territories, and more. All APIs are rate-limited to 3 requests/second. To pass authorization for any API you must supply a valid bearer token with each request. You must also make each request from a secure server (SSL). The first step to getting started is generating an access token. To do so, supply the /api/v1/token endpoint with a set of credentials (either with the --user username:password header in a cURL request or via form data with inputs for username and password). You will then receive the token to cache client-side, with which you will be able to access the resources you need.
This documentation provides examples for accessing Map My Customers web services APIs with:
For more examples of how to build with the API, reach out to support(at)mapmycustomers.me and we can provide additional language examples.
The token API allows you to obtain a new access token (in the form of a JSON response) to cache on the client side for future resource requests via endpoints in this documentation. Tokens last for 6 months per issuance. They are available for use 10 seconds after creation.
curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/token {
"token":"eyJ0eXAiOiJKV1QiCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE0OTYyODI4NDMsImp0aSI6IjZKRSVMU1FbktZPSIsImlzcyI6Im1hcG15Y3VzdG9tZXJzLm1lIiwibmJmIjoxNDk2MjgyODUzLCJleHAiOjE0OTYyODI5MTMsImRhdGEiOnsib2JqZWN0SWQiOiJnam1WVXJ5aG9JIiwidXNlcm5hbWUiOiJ0ZXN0YmFnQGdtYWlsLmNvbSJ9fQ.IxYi_22l6o18vlZMGO8VB4SDdHwFG9KhLAwyrjCeDV9DjY8QKaTRTqQecVLGTxlJLXpsj_iNNDJhX-5En8GBg"
}The customers API allows you to pull all of your pins and contacts data for your account.
Returns an array of all the customers for your account (i.e. both pins & contacts -- regardless of whether they are mapped or unmapped).
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/customers[
{
"id":"rSOUoiTGTh",
"name":"new5",
"company":"",
"address":"360 County Road S-22-779",
"city":"Pawleys Island",
"state":"South Carolina",
"zip":"29585",
"country":"United States",
"email":"",
"phone":"",
"color":"red",
"groups":["SC","New Leads"],
"dealAmount":null,
"notes":"",
"latitude":33.43213,
"longitude":-79.13183,
"lastVisit":1464295966,
"numVisits":3,
"remindAt":1466124582,
"remindType":"Visit Again",
"custom0":"",
"custom1":"",
"custom2":"",
"custom3":"",
"custom4":"",
"custom5":"",
"custom6":"",
"custom7":"",
"custom8":"",
"custom9":"",
"createdAt":{"date":"2016-05-21 02:27:42","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-24 04:28:39","timezone_type":2,"timezone":"Z"}
}
...
]Returns a single, unique customer from your account designated by an objectid ("id").
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/customers/rSOUoiTGTh{
"id":"rSOUoiTGTh",
"name":"new5",
"company":"",
"address":"360 County Road S-22-779",
"city":"Pawleys Island",
"state":"South Carolina",
"zip":"29585",
"country":"United States",
"email":"",
"phone":"",
"color":"red",
"groups":["SC","New Leads"],
"dealAmount":null,
"notes":"",
"latitude":33.43213,
"longitude":-79.13183,
"lastVisit":1464295966,
"numVisits":3,
"remindAt":1466124582,
"remindType":"Visit Again",
"custom0":"",
"custom1":"",
"custom2":"",
"custom3":"",
"custom4":"",
"custom5":"",
"custom6":"",
"custom7":"",
"custom8":"",
"custom9":"",
"createdAt":{"date":"2016-05-21 02:27:42","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-24 04:28:39","timezone_type":2,"timezone":"Z"}
}Returns an array of customers from your account that match the search term provided. Case-insensitive. Fields searched include: name, company, address, city, state, zip (postal code), and country.
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/customers/search/island[
{
"id":"rSOUoiTGTh",
"name":"new5",
"company":"",
"address":"360 County Road S-22-779",
"city":"Pawleys Island",
"state":"South Carolina",
"zip":"29585",
"country":"United States",
"email":"",
"phone":"",
"color":"red",
"groups":["SC","New Leads"],
"dealAmount":null,
"notes":"",
"latitude":33.43213,
"longitude":-79.13183,
"lastVisit":1464295966,
"numVisits":3,
"remindAt":1466124582,
"remindType":"Visit Again",
"custom0":"",
"custom1":"",
"custom2":"",
"custom3":"",
"custom4":"",
"custom5":"",
"custom6":"",
"custom7":"",
"custom8":"",
"custom9":"",
"createdAt":{"date":"2016-05-21 02:27:42","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-24 04:28:39","timezone_type":2,"timezone":"Z"}
}
...
]Creates a new customer in your authorized account from the JSON data provided. All parameters are optional, except that you must have at least a company or contact name provided in the payload. An image or PDF file can be attached as a base64 encoded string. Files may not be over 5MB in size.
curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X POST -d '{"name":"xyz","company":"abc","address":"6399 ridge road","city":"sharon center","state":"ohio","file":$base64file}' https://www.mapmycustomers.me/api/v1/customers{
"message":"Object created."
}Creates a new customer in your authorized account from the JSON data provided.
curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X PUT -d '{"name":"xyz","company":"abc","address":"6399 ridge road","city":"sharon center","state":"ohio"}' https://www.mapmycustomers.me/api/v1/customers/rSOUoiTGTh{
"message":"Customer with objectid rSOUoiTGTh successfully updated."
}Deletes an existing customer in your authorized account from the objectid provided.
curl -H "Authorization: Bearer {token}" -X DELETE https://www.mapmycustomers.me/api/v1/customers/rSOUoiTGTh{
"message":"Customer deleted with objectid rSOUoiTGTh."
}The routes API allows you to pull all of your routes data for your account.
Returns an array of all the routes for your account.
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/routes[
{
"id":"h8e44x3Ope",
"name":"east half",
"points":["35.37376,-89.87562","35.20126,-87.02965","35.89256,-84.14553","34.00071,-81.03481","35.22709,-80.84313"],
"createdAt":{"date":"2016-05-06 23:32:06","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-25 00:47:46","timezone_type":2,"timezone":"Z"}
},
{
"id":"GuWxXoPS4P",
"name":"New Mexico",
"points":["35.692130,-105.939590"],
"createdAt":{"date":"2016-05-06 23:30:17","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-25 16:23:34","timezone_type":2,"timezone":"Z"}
}
]Creates a new route in your authorized account from the JSON data provided. Points in JSON provided are the ids of customer objects returned from endpoints above. Thus, to create a new route the pins must already exist for the current user.
curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X POST -d '{"routeName":"my-route-name","customerIds":["Amy5CnIySf","Nk3vFYz1gJ"]}' https://www.mapmycustomers.me/api/v1/routes{
"message":"Object created."
}The territories API allows you to pull all of your territories data for your account.
Returns an array of all the territories for your account.
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/territories[
{
"id":"h8e44x3Ope",
"name":"Southern Track",
"points":["35.37376,-89.87562","35.20126,-87.02965","35.89256,-84.14553","34.00071,-81.03481","35.22709,-80.84313"],
"createdAt":{"date":"2016-05-06 23:32:06","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-25 00:47:46","timezone_type":2,"timezone":"Z"}
},
{
"id":"GuWxXoPS4P",
"name":"New Leads",
"points":["35.692130,-105.939590"],
"createdAt":{"date":"2016-05-06 23:30:17","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-25 16:23:34","timezone_type":2,"timezone":"Z"}
}
]The user info API allows you to pull all of your user metadata for your account.
Returns an object with all the metadata for your account.
curl -H "Authorization: Bearer {token}" https://www.mapmycustomers.me/api/v1/user{
"username":"jack@gmail.com",
"name":"jack daniels",
"phone":"432-456-7891",
"numPins":50000,
"colors":["black","green","blue","grey","orange","pink","purple","red","teal","yellow","neon red","neon yellow","neon green","neon blue","neon purple"],
"numGroups":500,
"groups":["Ohio","Latest Finds","Pittsburgh"],
"hiddenGroups":[],
"requiredGroups":["Ohio"],
"createdAt":{"date":"2014-12-18 17:32:32","timezone_type":2,"timezone":"Z"},
"updatedAt":{"date":"2016-05-26 18:11:03","timezone_type":2,"timezone":"Z"}
}Updates the custom fields of a user from the JSON data provided.
curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X PUT -d '{"birthday":0,"socialStatus":1,"salesToDate":2}' https://www.mapmycustomers.me/api/v1/user/customfields{
"message":"User's custom fields successfully updated."
}