Overview
The Download API allows individual franchise locations to automate data extraction without requiring setup at the brand level. This means an organization (franchisee) can configure its own API access independently, which is especially useful if they use third-party tools for custom reporting or analytics.
While users can manually export Excel reports and perform their own ETL processes, the Download API provides a faster, automated alternative. To enable it, you'll need to generate an API Key at the organization level. Make sure the API Key’s Status is set to Org.
Once your API Key is configured, no further setup is needed in serviceminder. For guidance on creating and managing API keys, please refer to API Key Configuration.
This article will review:
If your brand is interested in custom reporting, please contact our Support team or your Account Manager at serviceminder to learn more about SM Insights. This is our solution to custom data reporting and allows franchisees and franchisors to see these reports directly in serviceminder.
Download API for Orgs
The overall flow is:
- Start Download
- Receive DownloadId in Response
- Check Status of download w/ the ID
- When complete, Get Download
For org-level downloads, the User Id is a required field in the payload. This can be found in SM, when you view or edit your user it’s the numbers at the end of the URL. As long as that user has access to/permission for Reports, the download will run.
Things to note:
- There is a 25k limit to records on each download; if you believe you’ll be surpassing this, you can use pagination by using the RowId parameter
- In your first request, set the RowId to 0
- In your follow-up request, set the RowId to be the highest Id from the last download +1. This Id field is not the actual row #, but the Id of the record in that final row
- These downloads will also be downloadable in SM in your download queue from the Reports/Downloads section
Start Download
POST https://serviceminder.com/api/download/startdownload
Payload example:
{
"ApiKey": "your-api-key",
"Kind": "contacts",
"CreatedFrom": "01/01/2023",
"UserId": your-user-id,
"Contacts":
{
"WithEmails": true,
"WithoutEmails": true,
"IncludeCustomFields": true
}
Below is a list of common parameters. Please refer to our API Documentation Page for a complete and updated list.
Additional “Kind”s can be requested, highlighted in yellow, and additional parameters can be set. The Kind should just be changed out, as well as the object.
| Parameter | Type |
|---|---|
| CreatedFrom | datetime |
| CreatedThrough | datetime |
| UpdatedFrom | datetime |
| UpdatedThrough | datetime |
| DateFrom | datetime |
| DateThrough | datetime |
| CompletedBefore | datetime |
| CompletedAfter | datetime |
| OrganizationId | int32 |
| RowId | int32 |
| Kind | string |
| UserId | int32 |
| ApiKey | string |
| Appointments | downloadappointmentsettings |
| Contacts | downloadcontactsettings |
| Deposits | downloaddepositsettings |
| Invoices | downloadinvoicesettings |
| InvoiceLines | downloadinvoicelinesettings |
| Proposals | downloadproposalsettings |
| Services | downloadservicesettings |
| CampaignBudgets | downloadcampaignbudgetsettings |
| RevenueForecasts | downloadrevenueforecastsettings |
| ChannelsCampaigns | downloadchannelscampaignssettings |
Download Status
POST https://serviceminder.com/api/download/downloadstatus
{
"ApiKey": "your-key-here",
"DownloadId": "download-id"
}
Get Download
POST https://serviceminder.com/api/download/getdo
wnload
{
"ApiKey": "your-key-here",
"DownloadId": "download-id"
}
