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, and5
: Volunteer Applicant. - orgs int - A comma separated list of
org_id
's for the organizations associated with the contact. This field will benull
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 benull
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
andlname
fields. - Email string - Full string match on
email
field. - NameOrEmail string - Substring matches either
email
orfname
andlname
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, and5
: 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."
]
}