Introduction

The MOWScheduler Volunteer Application Advanced Integration features share a common set of field definitions used to capture volunteer application data. This document details how information is captured, and lists some extra control fields that are used to fine-tune integration-related options.

Standard Fields

MOWScheduler provides a set of standard fields for tracking contacts. Simply use the API Field Names below when you submit your contact and the data will appear in the appropriate field in the contact profile. You may use as many of these fields as you want, but you must include the fields marked "required". The standard field names are case sensitive. Note: If you're using a legacy form or form-builder system such as JotForm that doesn't easily allow you to specify our standard field names, we can set up a custom field mapping to allow use of your existing form fields. Contact us if you need this.

API Field Name	Suggested Form Label	Required	Example Data	Notes
First_Name	First Name	✔︎	John
Last_Name	Last Name		Smith
Street	Street		123 Main St.
City	City		Syracuse
State_Province	State/Province		NY	Use spelled out name, or 2 letter postal abbreviation.
Postal_Code	Postal Code		13202
Country	Country		United States	Use spelled out name or ISO-3166-1 code values.
Email	Email	✔︎	john@domain.com	Submission rejected if this email is already assigned to a Contact in our database
Alternate_Emails	Alternate Emails		john@domain1.com, john@domain2.com	Separate multiple emails with a comma.
Home_Phone	Home Phone		111-222-3333	See note below about Accepted Phone Number Formats.
Mobile_Phone	Mobile Phone		111-222-3333	See note below about Accepted Phone Number Formats.
Work_Phone	Work Phone		111-222-3333	See note below about Accepted Phone Number Formats.
Company_ID	Company		23	integer company_id, can be found in Organizations export file
Company	Company		XYZ Associates	text field, will populate the contact Organizations field only on exact match
Birthday	Birth Date		07/07/1977	See notes below about Birthday Handling and accepted date formats.
Birthday_Month	Birthday: Month		12	1: January, 2: February, etc. See note below about Birthday Handling
Birthday_Day	Birthday: Day		15	1-31. See note below about Birthday Handling
Birthday_Year	Birthday: Year		1980	Use 4 digits. See note below about Birthday Handling
Preferred_Communication	Preferred Method(s) of Communication		E,P	E: Email, P: Phone, T: Text Message; Use comma separated list for multiple values.
Drivers_Info	Drivers License #		343-33-444
License_Expiration	Drivers License Expiration Date		04/05/2021	See note below about accepted date formats.
Insurance_Info	Auto Insurance Information
Insurance_Expiration	Auto Insurance Expiration Date		01/01/2020	See note below about accepted date formats.
Tags	Contact Tags		2,3	contact tag ids for existing contact tags to be assigned to the contact based on checkbox or ? in form
Emergency_Contact	Emergency Contact Info		John Roe (brother) 315-555-1212	text field with info useful in case of emergency, should include name, phone, relationship

Birth Date Handling

You may submit birthday as either a complete date in the Birthday field, or separate Birthday_Month, Birthday_Day and (optional) Birthday_Year fields. Some organizations prefer to make the year optional so they can offer birthday greetings to their volunteers without asking for a birth year. If you'd prefer a real date of birth, make all 3 fields required in your form, or use the combined Birthday field.

Accepted Date Formats

• mm/dd/yyyy
• yyyy-mm-dd

Accepted Phone Number Formats

• (111) 111-1111
• 111-111-1111
• 1111111111
• +1 (111) 111-1111
• 1 (111) 111-1111
• 1 111 111-1111

Custom Fields

Custom fields can be passed along with your submissions. Simply prepend the field name for your custom field with X-. For example, if your custom field is Favorite_Color, send X-Favorite_Color.

Custom fields are stored in the Volunteer Application Detail note under the contact as key-value pairs. For example:

Custom Fields
-----------------------

Favorite_Color: Red
Shirt_Size: Medium
Volunteer_Task: Food Packer
Sports_Team: Bills, Colts

Notes

• Standard field names are case sensitive
• Custom field values are recorded as sent. You should avoid sending coded (e.g. html entity-encoded) values.
• If a given custom field name is repeated, the key will appear once, and values will recorded as a comma separated string.
• Field data must be a UTF-8 encoded string. (if you don't know what that means, you probably don't need to worry about it)
• Field values are limited to 3,000 characters.
• You may include up to 50 custom fields.
• If your software does not allow dashes in field names (for example, the Drupal 7 webform module), you may prefix your custom field names with X_ instead of X-.
• Fields submitted that are not either a Standard Field or prefixed with X- or X_ will not be recorded.

Meta Fields

Meta Fields are extra control fields used to configure processing options and support special features. They do not appear in the data recorded for the contact.

API Field Name	Used for	Required	Example Data	Notes
API_Key	Simple POST, webhook API	✔︎	abc123def567	Key value used to authenticate your submissons.
API_Mode	webhook API		1	0: Disabled (default) After application is submitted, redirect to url specified by Thank_You_URL or emit a simple generic Thank You page. 1: Enabled Return a JSON string with submission results.
Test_Mode	Simple POST		1	When running in Standard Mode: 0: Disabled (default) Submission is recorded and user is redirected to Thank You page. 1: Enabled Submission details are echoed back in summary form. Note: Test_Mode has no effect when API_Mode is enabled.
Thank_You_URL	Simple POST		https://yourmow.org/thanks	When API_Mode is disabled, end user is redirected to the specified url after their submission is recorded.
Comments	Simple POST		None	Spam trap honeypot. If this field contains any data, the submission will be rejected. See Spam Mitigation section for more details.

Spam Mitigation - level one: Spam Trap

Forms on public websites are often targets for spambots – automated spiders that wander around the web looking for forms. The spambot puts its irrelevant message in whatever fields it can find, and submits the form in the hopes that the posted content will show up somewhere where it will be seen. These submissions would show up as bogus entries in your contacts database. Quite annoying.

Spambots generally arenʼt very sophisticated, and they can be effectively defeated by using a CAPTCHA, the most common example being to ask your users to type in the text from a distorted text image. This works, but it puts a small burden your users.

Our first line of defense against spam is a simple method called a spam trap or honeypot. We add a field to your form that users canʼt see, but that the spambots canʼt easily identify as a hidden field. The spambots will typically insert content into this field. If the field isnʼt empty, itʼs usually a spambot submission, and we reject it with an appropriate error message. The field contains a label that instructs users of alternative browsers (handicapped-accessible screen readers, for example) to leave the field empty. This method is very effective, and causes no problems for legitimate users.

To implement the spam trap, simply add the following hidden span tag containing the empty field Comments in your form:

<span style="display:none;visibility:hidden;">
  <label for="Comments">
    Ignore this text box.
    It is used to detect spambots.
    If you enter anything into this
    text box, your submission will
    be rejected.
  </label>
  <input type="text" name="Comments" size="1" value="" id="Comments">
</span>

Spam Mitigation - level two: reCaptcha

If the simple spam trap isn't doing a good enough job of discouraging the bots from abusing your Simple POST form, we support the popular Google reCaptcha service. This is the familiar "I'm not a robot" checkbox. It's a very effective form of captcha, and less annoying to most users than the old blurred text or image recognition approaches. Details on implementing this method can be found in the Simple POST Setup guide. The reCaptcha javascript code automatically adds an extra field g-recaptcha-response to your form data which is used by our servers to verify the captcha.

Note: Spam mitigation is only enforced when API_Mode is disabled. When API_Mode is enabled, your form front end system should provide spam mitigation directly.