Using ServiceMinder's API - Intermediate to Advanced

Overview

ServiceMinder has an open API, which means that outside platforms can send and receive data to serviceminder, as long as they have an active API key (created inside of serviceminder.)  The most common usage of our API is adding leads (lead capture link), but some more intermediate uses are: 

In serviceminder's open API, there are different endpoints used for these actions. Endpoints are URLs that are designated for specific uses, i.e. the endpoint for creating a proposal is /proposal/create. Our API documentation page has a full list of endpoints that are available.  

Brand-scoped vs. Org-scoped Keys 

For adding leads, searching contacts, and finding orgs based on zips, a brand-scoped API key is needed. Oftentimes an outside platform uses this first to find the right org or create a contact before switching to an org-scoped key for further action. 

Org-scoped keys are set up in each individual org (meaning it can’t access other orgs’ data or push anything into another org.) This type of key is necessary for slot searching and booking an appt, creating (and updating or accepting proposals,) and uploading images/documents to existing contacts or proposals. It can also be used for lead capture but instead of distributing by zip, it pushes the lead directly into the org (however owned zip codes won’t go into the wrong org, an error will be thrown.) 

One-Step vs. Multi-Step Processes 

Some of the endpoints that are used are a one-step process – meaning that a single API call is made (POSTing a Request) and a single Response is given. An example is locating a contact: 

Using the endpoint  
https://serviceminder.com/api/contacts/locate 

The user can search a name, phone number, email address, or contact ID. The response given will return a contact, if one is found to match the data given. 

A multi-step process would be to book an appointment. For many of our endpoints, a Contact ID is required. So like in the above example, the ID would be in the response from locating the contact, which would be used in the next step. 

First using the Slot Search endpoint, the user can request availability. In addition to a Contact ID, a Service ID is necessary; that ID is found in the serviceminder account, at the end of the URL of the desired service. 

Once that Request is sent, a Response will show the available Slots. One of those can be “selected” by copy/pasting it into a new API call, to Book. Remember, all of this would need an org-scoped API key to work.  

Multi-step processes like this are a little harder to set up as the system used needs to be able to do an initial call, gather the response, parse that data into a new request, and so on. Many webforms don’t have the extended functionality to follow a multi-step process like that, so the limitations often lie with the platform or provider. 

Following similar instructions, proposals can be created via API as long as the user has a Contact ID, Service ID, Part IDs if necessary, and an org-scoped API key.  

There are some settings in serviceminder as well that can affect the response/outcome of some of your requests, which are outlined in troubleshooting. 

Troubleshooting/FAQs 

Leads 

Leads aren’t adding to my account, what’s wrong? For a lead to be added via API, serviceminder looks for a few things: 

Does every org need an individual API key? Not necessarily, if the outside platform is working for the entire brand; in that case, a single brand-scoped key can be used to distribute leads based on postal code to the right org. Unowned leads will drop into the org the brand-scoped key was created (typically a Franchise org or Parking Lot.) 

How many API keys can I have? 

Unlimited – it's recommended that a new key be created for unique platforms/lead sources for better tracking, but not necessary. 

Appointments 

I’m not getting any slots returned, why not? A number of things need to be set up and entered correctly for slot searching to return slots. Things to check: