MOWScheduler REST API Guide

Last Updated: 20200130jjc

Introduction

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

API Basics

Authentication

All REST transaction require authentication. Authentication is handled with the custom http header: X-ApiKey (not case-sensitive).

GET https://demo.mowscheduler.com/api/rest/v1/contact/search?Email=johnson

X-ApiKey: aaaa-bbbb-dddd-cccc
cache-control: no-cache

You can retrieve and reset your API Key in the MOWScheduler application by going to System Admin (the gear icon) > API Keys.

Note: when reseting the API key, all 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 Data Formatting

POST requests are expected to use standard HTTP form encoding.

Pagination

For methods that return multiple records, pagination is employed to keep request performance and size manageable. Results will include up to 10 records. If additional records match the search, the has_more meta field in the response will be true. 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:

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

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

{
  "object" : "list",
  "has_more" : true,
  "data" : [
    // 10 contact objects
  ]
}

That response contains the first 10 contacts, and has true for the has_more meta field. To retrieve the remaining 5 contacts, you would use the following request:

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

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,
  "data" : [
    // 5 contact objects
  ]
}

This response contains the remaining 5 contacts, and has_more is false to indicate that there are no more records to fetch.

Error Handling

In most cases, errant requests will return http status 400 Bad Request 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. Some useful tools:

Curl

The examples shown below use the popular Curl command line client. It's likely you already have it. Or get it from your package manager or app store, or download here. In addition to the command line, Curl libraries are available for many platforms.

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. More info and an Insomnia workspace file for our API are available here.

Objects

The top level objects in our API (currently Contacts and Companies) are described here, along with their associated API methods.

Contact

Contact is the entity that represents a volunteer type user in MOWScheduler.

Object Layout

{
  "object": "contact",
  "contact_type": "2",
  "alterateemail": null,
  "orgs": null,
  "orgnames": null,
  "contact_id": 268,
  "created": "2015-10-03T19:23:56",
  "email": "jjohnson@hotmail.com",
  "fname": "Josie",
  "lname": "Johnson",
  "modified": "2015-10-12T20:05:37",
  "phone_home": "(315)-234-0079",
  "phone_mobile": "(315)-342-1122",
  "phone_work": "(315)-445-0978",
  "address" : {
    "street": "456 Grant St",
    "city": "Syracuse",
    "stateProvince": "NY",
    "postalCode": "13212",
    "country": "US"
  },
  "dob_year": "1985",
  "dob_month": "6",
  "dob_day": "12",
  "start_date": "2017-01-31",
  "bkg_date": "2017-01-15",
  "title": "Salesperson",
  "pmethod": "e",
  "status": "1",
  "lastassignment_date" : "2017-09-01"
}
Field Details
  • object string - Relates object type, always returns contact.
  • contact_id int - The unique identifier for a contact in the MOWScheduler install. Read only.
  • contact_type int - Type of contact: 1: Staff, 2: Volunteer, 3: Client, 4: Other, and 5: Volunteer Applicant.
  • orgs int - A comma separated list of org_id's for the organizations associated with the contact. This field will be null if the contact is not associated with any organizations.
  • orgnames string - A comma separate list of organizations associated with the contact. This field will be null if the contact is not associated with any organizations. Read only.
  • fname string - First name.
  • lname string - Last name.
  • email string - Primary email address.
  • alternateemail string - Other email addresses for the contact, comma separated.
  • phone_num string - Home phone number.
  • phone_mobile string - Mobile phone number.
  • phone_work string - Work phone number.
  • address hash - Postal address information for the contact, see below for keys:
    • street string - Street Address
    • city string - City
    • stateProvince string - State or Province. Can be spelled out or use 2 letter abbreviation.
    • postalCode string - Postal/zip code.
    • country string - Country. Can be spelled out or use ISO-3166-1 code values.
  • dob_year - int - Contact birth year. See note about date of birth validation.
  • dob_month - int - Contact birth month. See note about date of birth validation.
  • dob_day - int - Contact birth day. See note about date of birth validation.
  • start_date - date - Volunteer start date in form YYYY-MM-DD.
  • bkg_date - date - Volunteer background check date in form YYYY-MM-DD.
  • title - string - Contact title.
  • pmethod - string - Contact's preferred notification methods. E: email, P: phone, T: text message. Submit multiple values as comma separated list.
  • status - int - Contact status: 1: Active, 2: Inactive.
  • created - timestamp - Time when contact record was created in UTC timezone. Read only.
  • modified - timestamp - Time when contact record was last modified in UTC timezone. Read only.
  • lastassignment_date - date - The date of the contact's last assignment.
Date of Birth Validation

Date of birth is collected as separate fields for year, month, and day. To set date of birth, you must provide at least month and day; year is optional.

Search Contacts

Endpoint
GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/search
Sample CURL Request
curl --request GET \
  --url 'https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/search?Name=John' \
  --header 'x-apikey: aaaa-bbbb-cccc-dddd'
Parameters
  • CreatedBefore timestamp - Matches contacts created on or before the specified timestamp.
  • CreatedAfter timestamp - Matches contacts created on or after the specified timestamp.
  • ModifiedAfter timestamp - Matches contacts modified after the specified timestamp.
  • AssignmentAfter date - Matches contacts with an assignment after specified date, not including today.
  • Name string - Substring match on fname and lname fields.
  • Email string - Full string match on email field.
  • NameOrEmail string - Substring matches either email or fname and lname fields (as used in the "quick search" in the web interface).
  • Organization string - Substring match on names of organizations related to contacts.
  • start_after integer - The contact_id of the last result entry to skip when using pagination. See Pagination section under API Basics above for more information.
  • RecentlyCreated integer - Matches contacts created in specified number of days. Allowed values are 1 through 7 inclusive.
  • ContactType integer - Matches contact type: 1: Staff, 2: Volunteer, 3: Client, 4: Other, and 5: Volunteer Applicant.
  • Status integer - Matches status 1 : active, 2 : inactive.
Response

Contacts that match all search parameters, sorted by created attribute, newest first.

{
  "object" : "list",
  "has_more" : false,
  "data" : [
    {
      "object": "contact",
      "alterateemail": null,
      "orgs": null,
      "orgnames": null,
      "contact_id": 334,
      "contact_type": 2,
      "created": "2015-10-03T19:23:58",
      "email": "njohnson@outlook.com",
      "fname": "Nick",
      "lname": "Johnson",
      "modified": "2015-10-12T20:05:38",
      "phone_home": "",
      "phone_mobile": "(315)-372-1122",
      "phone_work": "",
      "address" : {
        "street": "881 Genesee St",
        "city": "Dewitt",
        "stateProvince": "NY",
        "postalCode": "13214",
        "country": "US"
      },
      "dob_year": "1979",
      "dob_month": "1",
      "dob_day": "19",
      "bkg_date": "2015-02-03",
      "start_date": "2015-02-04",
      "title": "Supervisor",
      "status": "1",
      "pmethod": "E",
      "lastassignment_date" : "2015-05-05",
    },
    {
      "object": "contact",
      "alterateemail": null,
      "orgs": null,
      "orgnames": null,
      "contact_id": 268,
      "contact_type": 2,
      "created": "2015-10-03T19:23:56",
      "email": "jjohnson@hotmail.com",
      "fname": "Josie",
      "lname": "Johnson",
      "modified": "2015-10-12T20:05:37",
      "phone_home": "(315)-234-0079",
      "phone_mobile": "(315)-342-1122",
      "phone_work": "(315)-445-0978",
      "address" : {
        "street": "456 Grant St",
        "city": "Syracuse",
        "stateProvince": "NY",
        "postalCode": "13212",
        "country": "US"
      }
      "dob_year": "",
      "dob_month": "",
      "dob_day": "",
      "bkg_date": "",
      "start_date": "",
      "title": "",
      "status": "1",
      "pmethod": "T",
      "lastassignment_date" : "2016-01-11",
    }
  ]
}

Get Contact By Id

Endpoint
GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/:contact_id
Sample Curl Request
curl --request GET \
  --url 'https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/1' \
  --header 'x-apikey: aaaa-bbbb-cccc-dddd'
Response
{
  "object": "contact",
  "alterateemail": null,
  "orgs": null,
  "orgnames": null,
  "contact_id": 334,
  "contact_type": 2,
  "created": "2015-10-03T19:23:58",
  "email": "njohnson@outlook.com",
  "fname": "Nick",
  "lname": "Johnson",
  "modified": "2015-10-12T20:05:38",
  "phone_home": "",
  "phone_mobile": "(315)-372-1122",
  "phone_work": "",
  "address" : {
    "street": "881 Genesee St",
    "city": "Dewitt",
    "stateProvince": "NY",
    "postalCode": "13214",
    "country": "US"
  },
  "dob_year": "",
  "dob_month": "",
  "dob_day": "",
  "bkg_date": "",
  "start_date": "",
  "title": "",
  "status": "1",
  "pmethod": "T",
  "lastassignment_date" : "2016-01-11"
}

Create A New Contact

Endpoint
POST https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact
Sample Curl Request
curl --request POST \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc' \
  --data fname=Fred \
  --data lname=Rogers \
  --data email=fred.rogers@email.com
Response

Successful requests will return the full contact object.

{
  "object": "contact",
  "alterateemail": null,
  "orgs": null,
  "orgnames": null,
  "contact_id": 777,
  "contact_id": 2,
  "created": "2019-08-06T14:33:00",
  "email": "fred.rogers@email.com",
  "fname": "Fred",
  "lname": "Rogers",
  "phone_home": "",
  "phone_mobile": "",
  "phone_work": "",
  "modified": "2019-08-06T14:33:00",
  "address" : {
    "street": "",
    "city": "",
    "stateProvince": "",
    "postalCode": "",
    "country": ""
  },
  "dob_year": "",
  "dob_month": "",
  "dob_day": "",
  "bkg_date": "",
  "start_date": "",
  "title": "",
  "status": "1",
  "pmethod": "",
  "lastassignment_date" : "2019-12-31"
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "'email' field missing."
  ]
}

Update an Existing Contact

Endpoint
POST https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/:contact_id
Sample Curl Request
curl --request POST \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/12 \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc' \
  --data fname=Mary \
  --data lname=Simms \

Note: only fields included in request will be updated; all other fields will remain unchanged.

Response

Successful requests will return the full contact object.

{
  "object": "contact",
  "alterateemail": null,
  "orgs": null,
  "orgnames": null,
  "contact_id": 777,
  "contact_type": 2,
  "created": "2019-08-06T14:33:00",
  "email": "mary.simms@email.com",
  "fname": "Mary",
  "lname": "Simms",
  "modified": "2019-08-06T14:50:00",
  "phone_home": "",
  "phone_mobile": "111-222-3564",
  "phone_work": "",
  "address" : {
    "street": "",
    "city": "",
    "stateProvince": "",
    "postalCode": "",
    "country": ""
  },
  "dob_year": "",
  "dob_month": "",
  "dob_day": "",
  "bkg_date": "",
  "start_date": "",
  "title": "",
  "status": "1",
  "pmethod": "",
  "lastassignment_date": "2019-08-07",
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "Unknown contact_id: 888."
  ]
}

Delete an Existing Contact

Endpoint
DELETE https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/:contact_id
Sample Curl Request
curl --request DELETE \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/12 \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc'

Note: deleting a contact will automatically remove all their current assignments.

Response

Successful requests will return the json similar to:

{
  "contact_id": 777,
  "object": "customer",
  "deleted": true
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "Unable to delete contact, contact deleted previously."
  ]
}

Organization

Organization is the entity that represents a volunteer group like a company or church.

Object Layout

{
  "object": "organization",
  "org_id": 123,
  "status": 1,
  "name": 'Jones Incorporated',
  "main_contact": 113,
  "main_contact_name": "John Smith",
  "created": "2015-10-03T19:23:58",
  "modified": "2016-02-03T12:12:58"
}

Field Details

  • object string - Relates object type, always returns organization.
  • org_id int - The unique identifier for an organization in the MOWScheduler install. Read only.
  • status int - Status for the organization: 1 for active, 0 for inactive.
  • name string - Name of the organization.
  • main_contact int - Contact Id for the main contact for the organization. Will be null if organization doesn't have an assigned main contact.
  • main_contact_name string - Name for the main contact for the organization. Will be null if organization doesn't have an assigned main contact. Read only.
  • created - timestamp - Time when organization record was created in UTC timezone. Read only.
  • modified - timestamp - Time when organization record was last modified in UTC timezone. Read only.

Requests

Search Organizations

Endpoint
GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/search
Sample Curl Request
curl --request GET \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/search?Name=State \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc'
Parameters
  • CreatedBefore timestamp - Matches organizations created on or before the specified timestamp.
  • CreatedAfter timestamp - Matches organizations created on or after the specified timestamp.
  • ModifiedAfter timestamp - Matches organizations modified after the specified timestamp.
  • Name string - Substring match on organization name fields.
  • start_after integer - Used to specify org_id show to results after when using pagination. See Pagination section under API Basics above for more information.
Response
{
  "object" : "list",
  "has_more" : false,
  "data" : [
    {
      "object": "organization",
      "org_id": 123,
      "status": 1,
      "name": 'Jones Incorporated',
      "main_contact": 113,
      "main_contact_name": "John Smith",
      "created": "2015-10-03T19:23:58",
      "modified": "2016-02-03T12:12:58"
    },
    {
      "object": "organization",
      "org_id": 442,
      "status": 1,
      "name": 'Jackson Services',
      "main_contact": null,
      "main_contact_name": null,
      "created": "2017-10-03T19:23:58",
      "modified": "2017-10-03T19:23:58"
    },
  ]
}

Get Organization By Id

Endpoint
GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/:org_id
Sample Curl Request
curl --request GET \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/1 \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc'
Response
{
  "object": "organization",
  "org_id": 123,
  "status": 1,
  "name": 'Jones Incorporated',
  "main_contact": 113,
  "main_contact_name": "John Smith",
  "created": "2015-10-03T19:23:58",
  "modified": "2016-02-03T12:12:58"
}

Create A New Organization

Endpoint
POST https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization
Sample Curl Request
curl --request POST \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc' \
  --data 'name=Edwards Associates'
Response

Successful requests will return the full organization object.

{
  "object": "organization",
  "org_id": 123,
  "status": 1,
  "name": 'Edwards Associates',
  "main_contact": null,
  "main_contact_name": "null",
  "created": "2019-08-01T12:00:00",
  "modified": "2019-08-01T12:00:00"
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "'name' field missing."
  ]
}

Update an Existing Organization

Endpoint
POST https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/:org_id
Sample Curl Request
curl --request POST \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/442 \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc' \
  --data 'name=Fitz Systems'
  --data 'main_contact=442'

Note: only fields included in request will be updated; all other fields will remain unchanged.

Response

Successful requests will return the full organization object.

{
  "object": "organization",
  "org_id": 123,
  "status": 1,
  "name": 'Fitz Systems',
  "main_contact": 442,
  "main_contact_name": "James Fitz",
  "created": "2019-08-01T12:00:00",
  "modified": "2019-08-01T14:00:00"
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "'main_contact': 442, doesn't match any contact on file."
  ]
}

Delete an Existing Organization

Endpoint
DELETE https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/:org_id
Request
curl --request DELETE \
  --url https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/organization/223 \
  --header 'x-apikey: aaaa-bbbb-dddd-cccc'

Note: any contacts that were associated with the organization being delete will no longer be associated with that organization.

Response

Successful requests will return the json similar to:

{
  "org_id": 223,
  "object": "organization",
  "deleted": true
}

Requests with errors will be returned with a 400 status code and details about error(s) in JSON similar to:

{
  "object": "error",
  "errors": [
    "'org_id': 223 unknown."
  ]
}