Last Updated: 20240226JM

Introduction

The MOWScheduler REST API allows direct access to the database behind your MOWScheduler install. You can create, modify, and delete contact, organization, and job records easily using simple REST transactions.

This page includes an overview of API usage. For technical details on specific API methods, parameters, and responses, please see the interactive MOW Scheduler REST API Reference

API Basics

Endpoints

The "base URL" for your Scheduler site is https://{yoursite}.mowscheduler.com/api/rest/v1 and all API method paths are relative to that.

Authentication

All REST transactions require authentication. Authentication is handled with the X-ApiKey http header, for example: X-ApiKey: aaaa-bbbb-dddd-cccc. Note that the http header name X-ApiKey is not case sensistive, so x-apikey is equally valid. However the api key value is case sensitive.

You can retrieve and/or reset your API Key in the MOWScheduler application at System Admin > Data Integration > API Keys.

Note: when reseting the API key, any integrations using the old key will cease to work immediately. Please take care to coordinate your key reset and related updates in your integrations to ensure ongoing connectivity.

POST and PATCH Data Formatting

POST and PATCH requests are expected to use standard HTTP form encoding, aka application/x-www-form-urlencoded. We may add support for JSON data in the request body in the future, let us know if you're interested in this option.

PATCH requests update only fields included in the request body. If you include a field in the request and give it a null or empty string value, it will clear any existing value in the database.

Normally POST is used only to the create a new object, and its identifier will be assigned automatically by the server. However you can perform updates via POST to a specific existing object by including a valid object ID in the path. In this case the POST emulates the PATCH operation and updates any fields included in the request. This capability was added to facilitate development with older HTTP clients that didn't support the PATCH method, however this should not be a limitation in most recent HTTP clients, and this capability will probably be removed in a future version of this API. Bottom line: use PATCH for updates if possible.

Example PATCH request (via Curl command line HTTP client, see Client Tools section below):

curl --request PATCH \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/442 \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-apikey: [yourapikeyhere]' \
  --data 'name=Fitz Systems'
  --data 'main_contact='

things to note in this example:

• this request is intended to update existing Organization with unique ID 442
• the Organization name will be updated
• any existing main contact will be removed
• all other properties will be unchanged
• content-type: application/x-www-form-urlencoded
• Curl automatically combines and encodes data fields to construct the request body, but the data can be formatted as one parameter --data 'name=Fitz%20Systems&main_contact='

API Responses

all API responses are returned as JSON with content-type: application/json; charset=utf-8. The content of the responses for specific API methods (both in success and error cases) is show in the MOW Scheduler REST API Reference.

Data Types

Dates use ISO 8601 date format (YYYY-MM-DD). Timestamps in responses use ISO 8601 format (YYYY-MM-DDThh:mm:ss) in the UTC timezone. Timestamps in request parameters can be sent in timestamp format (YYYY-MM-DDThh:mm:ss), mysql datetime (YYYY-MM-DD hh:mm:ss), or truncated date format (YYYY-MM-DD, which will be interpreted as YYYY-MM-DDT00:00:00 UTC)

Pagination

For search methods that return many records, pagination may be employed to keep request performance and response size manageable. Results will include up to page_size records (default 100 for Contact and Organization objects). If additional records match the search, the has_more meta field in the response will be true and the found_rows field will show the total number of rows (which in this case will be greater than page_size). To retrieve additional records, use the start_after search parameter with id for the last record of the proceeding set. You can repeat the process until the result contains has_more being false indicating that all records have been returned.

For example, say you run the following contact search with default page_size 100:

GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/search?Name=john

If there were 115 matches, the response would look similar to:

{
  "object" : "list",
  "has_more" : true,
  "found_rows" : 115,
  "data" : [
    // 100 contact objects
  ]
}

That response contains the first 100 contacts, and has true for the has_more meta field and total rows found in found_rows. To retrieve the remaining 15 contacts, you would use the following request:

GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/search?Name=john&start_after=82

where 82 is the contact_id from the last contact in the first response. The second response would look similar to:

{
  "object" : "list",
  "has_more" : false,
  "found_rows" : 15,
  "data" : [
    // 15 contact objects
  ]
}

the minimum page_size is 1, default is 100, and max is 5000 for Contact and Organization searches. Pagination is currently not supported for Job objects.

Note: unless your Scheduler database is very large, it's usually safe to specify a large page_size and avoid the need for paging.

Error Handling

In most cases, errant requests will return http status 400 Bad Request or 404 Not Found and include more information about the error(s) in json in the response body.

{
  "object": "error",
  "errors": [
    'First error...',
    'Second error...'
  ]
}

Client Tools

We don't currently provide any downloadable client library implementations of this API. Developers familiar with REST apis can code their own from scratch, or with the help of a REST client tool like Insomnia, or a general-purpose REST client or HTTP library.

Many API client development/testing tools can import the MOW Scheduler REST API spec in OpenAPI 3.0 format. An up-to-date copy of this spec is publicly available at https://demo.mowscheduler.com/static/openapi.yaml

In general these tools require you to enter the REST API key for your MOW Scheduler account, which you can get by logging into Scheduler and going to System Admin > Data Integration > API Keys

Some useful tools:

MOW Scheduler's embedded Swagger UI

We've included the web-based Swagger UI tool in the MOW Scheduler interface. It's configured by default to read the most recent version of our OpenAPI spec, and it allows you to interactively try out the various API methods by querying your own database with the interactive "Try it Out" feature, which also generates sample command line code, including the appropriate HTTP headers for authentication, etc.

You can find this in your MOW Scheduler interface under System Admin > Data Integration > REST API Tools

Curl

The examples shown in our interactive embedded interface use the popular Curl command line client. It's in your package manager or app store, or download here. In addition to the command line, Curl libraries are available for many platforms and may be used for API client development if you don't already have a preferred HTTP client library.

Insomnia

Insomnia is a REST development tool that helps you explore the API (sort of like Curl on steroids), and also provides the ability to generate API client code in several languages based on a workspace file. Insomnia can import our OpenAPI spec file.

Web-based Tools

Postman and SwaggerHub are web-based tools that are useful for API development and testing. Both can read our OpenAPI spec file

Sample Usage

Syncing two systems that both have REST apis can be as easy as this:

1. search MOW Scheduler for Contacts that have been added or updated recently, using the ModifiedAfter search param
2. for each Contact found, remap the field names and reformat the values as needed to meet the requirements of System X
3. push the Contact to System X

This workflow requires a small program that can "talk" to both APIs, you could call it middleware or a data broker, or ? It's fairly easy to write something like that from scratch, or you could use a third party web automation tool such as Zapier. It could be run on demand as needed, or on a regular scheduler depending on your needs.

Zapier hint: you could use the "Webhooks by Zapier" action to get the MOW Scheduler contacts (don't forget to add the x-apikey header), with a trigger such as "Every Day in Schedule" to run the sync daily.

Objects, Methods, and Responses

see the interactive MOW Scheduler REST API Reference for info on current API features