Introduction

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 the Basic Auth header on each request with your account credentials (e.g. user:password). You must also make each request from a secure server (SSL) and ask to be added to the whitelist of IPs by contacting Map My Customers support.

This documentation provides examples for accessing Map My Customers web services APIs with:

Customers

The customers API allows you to pull all of your pins and contacts data for your account.

Retrieve all customers

Returns an array of all the customers for your account (i.e. both pins & contacts -- regardless of whether they are mapped or unmapped).

GET
/api/v1/customers

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/customers

Example response

[
  {
    "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"}
  }
  ...
]

Retrieve a single customer

Returns a single, unique customer from your account designated by an objectid ("id").

GET
/api/v1/customers/{objectid}

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/customers/rSOUoiTGTh

Example response

{
  "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"}
}

Search for customers

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.

GET
/api/v1/customers/search/{searchterm}

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/customers/search/island

Example response

[
  {
    "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"}
  }
  ...
]

Create a new customer

Creates a new customer in your authorized account from the JSON data provided.

POST
/api/v1/customers

Example request

curl --user user_email:user_password -H "Content-Type: application/json" -X POST -d '{"name":"xyz","company":"abc","address":"6399 ridge road","city":"sharon center","state":"ohio"}' https://www.mapmycustomers.me/api/v1/customers

Example response

{
  "message":"Object created."
}

Update an existing customer

Creates a new customer in your authorized account from the JSON data provided.

PUT
/api/v1/customers/{objectid}

Example request

curl --user user_email:user_password -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

Example response

{
  "message":"Customer with objectid rSOUoiTGTh successfully updated."
}

Delete an existing customer

Deletes an existing customer in your authorized account from the objectid provided.

DELETE
/api/v1/customers/{objectid}

Example request

curl --user user_email:user_password -X DELETE https://www.mapmycustomers.me/api/v1/customers/rSOUoiTGTh

Example response

{
  "message":"Customer deleted with objectid rSOUoiTGTh."
}

Routes

The routes API allows you to pull all of your routes data for your account.

Return all routes

Returns an array of all the routes for your account.

GET
/api/v1/routes

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/routes

Example response

[
  {
    "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"}
  }
]

Create a new route

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.

POST
/api/v1/routes

Example request

curl --user user_email:user_password -H "Content-Type: application/json" -X POST -d '{"routeName":"my-route-name","customerIds":["Amy5CnIySf","Nk3vFYz1gJ"]}' https://www.mapmycustomers.me/api/v1/routes

Example response

{
  "message":"Object created."
}

Territories

The territories API allows you to pull all of your territories data for your account.

Return all territories

Returns an array of all the territories for your account.

GET
/api/v1/territories

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/territories

Example response

[
  {
    "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"}
  }
]

User Info

The user info API allows you to pull all of your user metadata for your account.

Return all user metadata

Returns an object with all the metadata for your account.

GET
/api/v1/user

Example request

curl --user user_email:user_password https://www.mapmycustomers.me/api/v1/user

Example response

{
  "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"}
}

Update a user's custom fields

Updates the custom fields of a user from the JSON data provided.

PUT
/api/v1/user/customfields

Example request

curl --user user_email:user_password -H "Content-Type: application/json" -X PUT -d '{"birthday":0,"socialStatus":1,"salesToDate":2}' https://www.mapmycustomers.me/api/v1/user/customfields

Example response

{
  "message":"User's custom fields successfully updated."
}
Show examples in:
Map My Customers API