IntroductionCustomersRoutesTerritoriesUpdatesUser Info

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

Token Issuance

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.

GET
/api/v1/token

Example request

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

Example response

  {
    "token":"eyJ0eXAiOiJKV1QiCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE0OTYyODI4NDMsImp0aSI6IjZKRSVMU1FbktZPSIsImlzcyI6Im1hcG15Y3VzdG9tZXJzLm1lIiwibmJmIjoxNDk2MjgyODUzLCJleHAiOjE0OTYyODI5MTMsImRhdGEiOnsib2JqZWN0SWQiOiJnam1WVXJ5aG9JIiwidXNlcm5hbWUiOiJ0ZXN0YmFnQGdtYWlsLmNvbSJ9fQ.IxYi_22l6o18vlZMGO8VB4SDdHwFG9KhLAwyrjCeDV9DjY8QKaTRTqQecVLGTxlJLXpsj_iNNDJhX-5En8GBg"
  }

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). If you're a team owner, all of the data for your team will be returned.

GET
/api/v1/customers

Example request

curl -H "Authorization: Bearer {token}" https://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"}
  }
  ...
]

Recently updated customers

Returns an array of all the customers recently updated for your account since a specific timestamp (i.e. both pins & contacts -- regardless of whether they are mapped or unmapped). If you're a team owner, all of the data for your team will be returned. The timestamp parameter passed in will be a normal unix timestamp (integer) of the "date time" you would like to use.

GET
/api/v1/updatedcustomers/{timestamp}

Example request

curl -H "Authorization: Bearer {token}" https://mapmycustomers.me/api/v1/updatedcustomers/1526515200

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"). If you're a team owner, every customer in your team will be considered.

GET
/api/v1/customers/{objectid}

Example request

curl -H "Authorization: Bearer {token}" https://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. If you're a team owner, every customer in your team will be searched for.

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

Example request

curl -H "Authorization: Bearer {token}" https://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. 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.

POST
/api/v1/customers

Example request

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","notes":"good lead should call again", "file":$base64file}' https://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. Including a 'notes' key will produce a new note for the existing customer.

PUT
/api/v1/customers/{objectid}

Example request

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://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 -H "Authorization: Bearer {token}" -X DELETE https://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 -H "Authorization: Bearer {token}" https://mapmycustomers.me/api/v1/routes

Example response

[
  {
    "id":"h8e44x3Ope",
    "name":"east half",
    "customerIds":["Amy5CnIySf","Nk3vFYz1gJ"],
    "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",
    "customerIds":["Fnv3CnIymE","KSn3FYz1fd"],
    "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 -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X POST -d '{"routeName":"my-route-name","customerIds":["Amy5CnIySf","Nk3vFYz1gJ"]}' https://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 -H "Authorization: Bearer {token}" https://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"}
  }
]

Updates

The updates API allows you to pull all of the updates/activities you've made on your account.

Return all updates

Returns an array of all the updates for your account. Notes included are additional information related to the type of the update. Possible types include:

  • delete
  • integration
  • import
  • checkIn
  • newGroup
  • newRoute
  • leadStatusChange
  • pinEdit
  • newCustomer
  • photoUpload
  • addedNote
  • editedNote
  • emailSent
  • called
  • reminder
GET
/api/v1/updates

Example request

curl -H "Authorization: Bearer {token}" https://mapmycustomers.me/api/v1/updates

Example response

[
  {  
     "username":"jack@gmail.com",
     "customerId":"",
     "type":"import",
     "notes":"20 pins",
     "platform":"web",
     "createdAt":{  
        "date":"2018-01-04 19:37:42",
        "timezone_type":2,
        "timezone":"Z"
     }
  },
  {  
     "username":"test@tester.com",
     "customerId":"jl9xPVuk6z",
     "type":"addedNote",
     "notes":"Good chat with Jim about next steps.",
     "platform":"web",
     "createdAt":{  
        "date":"2018-01-04 19:39: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 -H "Authorization: Bearer {token}" https://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 -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X PUT -d '{"birthday":0,"socialStatus":1,"salesToDate":2}' https://mapmycustomers.me/api/v1/user/customfields

Example response

{
  "message":"User's custom fields successfully updated."
}

Update a user's groups

Replaces the groups of a user from the JSON data provided.

PUT
/api/v1/user/groups

Example request

curl -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -X PUT -d '{"groups":["group1","group2","group3"]}' https://mapmycustomers.me/api/v1/user/groups

Example response

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