MOWScheduler REST API Guide

Last Updated: 20220627jjc

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 and PATCH Data Formatting

POST and PATCH requests are expected to use standard HTTP form encoding.

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 methods that return multiple records, pagination is employed to keep request performance and size manageable. Results will include up to page_size records (default 10). 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:

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

That response contains the first 10 contacts, and has true for the has_more meta field and total rows found in found_rows. 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,
  "found_rows" : 5,
  "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 and found_rows is equal to the number of records in data.

the minimum page_size is 1, and max is 100

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, Contact Tags, and Organizations) 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"
  "tags": "1,2",
  "tagnames": "Student; Mercy College"
}
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.
  • tags string - A comma separated list of tag_id's for the contact tags associated with the contact. This field will be null if the contact is not associated with any contact tags. See ContactTags entity below for more details.
  • tagnames string - A comma separated list of contact tags associated with the contact. This field will be null if the contact is not associated with any contact tags. Read only.
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.
  • page_size - The max number of result rows to return. Allowed values are 1 to 100, default is 10.
  • 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.
  • Tags string - One or more tag_id's, comma separated. Matches contacts that have all the specified tags.

parameters with type timestamp may be in ISO8601 date (YYYY-MM-DD) or datetime (YYYY-MM-DDThh:mm:ss) format in UTC timezone

Response

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

{
  "object" : "list",
  "has_more" : false,
  "found_rows" : 2,
  "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",
      "tags": null,
      "tagnames": null
    },
    {
      "object": "contact",
      "alterateemail": null,
      "orgs": null,
      "orgnames": null,
      "contact_id": 268,
      "contact_type": 2,
      ... etc ...
    }
  ]
}

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"
  "tags": "1",
  "tagnames": "Substitute"
}

Create A New Contact

Endpoint
POST https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact

Elements of the contact's address object are specified as individual fields, for example city='Whoville'

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 \
  --data tags=1
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",
  ... etc. ...
}

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
PATCH https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contact/:contact_id

Note: either POST or PATCH can be used for updating existing records, and both follow typical PATCH behavior: only fields included in request will be updated; all other fields will remain unchanged.

Elements of the contact's address object can be updated individually by the element name, for example city='Whoville'

To remove an existing value, include the field name in the request with empty string as the value, for example: tags=''

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 \
Response

Successful requests will return the full contact object.

{
  "object": "contact",
  "alterateemail": null,
  "orgs": null,
  "orgnames": null,
  "contact_id": 777,
  "contact_type": 2,
  ... etc. ...
}

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."
  ]
}

ContactTag

ContactTag is an entity that describes simple attributes that may be associated with contacts. Examples: St. John's Church, XYZ Power Company, and College Students.

Currently ContactTag resources are "read-only" in the REST api and may only be created or updated through the web interface (requires System Admin privileges)

Object Layout

{
  "object": "contactTag",
  "tag_id": 2,
  "name": "College Students",
  "color": "#FF0000",
  "modified": "2016-02-03T12:12:58"
}
Field Details
  • object string - Relates object type, always returns contactTag.
  • tag_id int - The unique identifier for a tag in the MOW Scheduler install.
  • name string - Name for the tag.
  • color string - Optional HTML hex color specification for the tag in MOW Scheduler frontend.
  • modified timestamp - The timestamp when tag entity was last modified.

Search ContactTags

Endpoint
GET https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contactTag/search
Sample CURL Request
curl --request GET \
  --url 'https://[your MOWScheduler install].mowscheduler.com/api/rest/v1/contactTag' \
  --header 'x-apikey: aaaa-bbbb-cccc-dddd'
Parameters
  • Name string - Matches on contact tag name fields.
  • ModifiedBefore timestamp - Matches contact tags modified before the specified timestamp.
  • ModifiedAfter timestamp - Matches contact tags modified after the specified timestamp.
  • 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.
  • page_size - The max number of result rows to return. Allowed values are 1 to 100, default is 10.
Response

Contact tags that match all search parameters, sorted by modified attribute, most recently updated first.

{
  "object" : "list",
  "has_more" : false,
  "found_rows" : 2,
  "data" : [
    {
      "object": "contactTag",
      "tag_id": 2,
      "name": "College Students",
      "color": "#FF0000",
      "modified": "2016-02-03T12:12:58"
    },
    {
      "object": "contactTag",
      "tag_id": 1,
      "name": "Substitute",
      "color": "#00FF00",
      "modified": "2016-02-01T12:12:58"
    }
  ]
}

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.
  • page_size - The max number of result rows to return. Allowed values are 1 to 100, default is 10.
Response
{
  "object" : "list",
  "has_more" : false,
  "found_rows" : 2,
  "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
PATCH 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: either POST or PATCH can be used for updating existing records, and both follow typical PATCH behavior: 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."
  ]
}