The goal of this document is to ensure that information provided by VolunteerMatch and our nonprofit members is presented in a clear and consistent manner across applications. This document is divided into sections based on the API calls and pages in your application that present the capabilities and data.
The easiest implementation option, for allowing users to search for volunteer opportunities, is to display a search form, accept some parameters – location, keywords, etc. – and then make a searchOpportunities call to the VolunteerMatch service. This offloads storage and search functionality to the VM service, relieving your system from needing to implement and optimize it. It allows for a number of pagination sizes and sort orders, and it will ensure that the most popular VolunteerMatch nation-wide opportunities are presented seamlessly to your users.
Search results are returned in response to the searchOpportunities call. They can be displayed as listed below.
Opportunity Title, which links to the Opportunity Detail page.
Organization Name.
Images: VolunteerMatch can provide access to a repository of images.
Date and Time.
Location or Virtual.
Opportunity Description.
Button, which links to the Opportunity Detail page.
Optional data: requirements, age groups, cause area, and shifts.
"Powered by VolunteerMatch" logo displayed in each listing; or if all the listings come from VolunteerMatch, the logo may appear in the footer of the page – bottom right corner.
Search Results Page: Sample UI
Opportunity Title.
Organization Name.
Opportunity Description.
Date and Time of opportunity.
Shifts available.
Open spots available, if opportunity limits number of connections from volunteers
Location or Virtual.
Opportunity photo, or VolunteerMatch default images related to cause areas.
Button to Express Interest or Sign Up.
"Powered by VolunteerMatch" logo required in the footer.
Optional: Map (lat/long provided), requirements, cause areas, skills, age groups
Opportunity Detail Page: Sample UI
In order for a volunteer to express interest or sign up for an opportunity in the VolunteerMatch network, the volunteer must be a member of the VM system. Setting up the member record and making the subsequent connection can be made with a single API call: createConnection. For simplicity we will make the following assumptions:
Our API partner will verify the volunteer's email address
Our API partner will require the volunteer to agree to Terms of Use that cover VolunteerMatch.
Username and password will be managed by the API partner, and should not be sent with user information when making a connection
The volunteer will be signed in with VolunteerMatch's API partner, and the partner will pass VolunteerMatch the required data below to connect the user.
Once a volunteer finds an opportunity and is signed in, he or she expresses interest or signs up by clicking a button and the VolunteerMatch API facilitates the connection to the nonprofit when the createConnection mutation is called. Note that, if an opportunity has shifts, a volunteer should be able to express interest or sign up in multiple shift IDs with one connection request.
The following fields are required for ALL createConnection calls:
Volunteer email (primary key)
Opportunity ID
Array of Shift IDs (optional, if applicable)
Answers to any required custom questions (searchOpportunities/customFields)
Comments to the organization (if supplied by volunteer)
The following fields are only required for a new volunteer, defined as an email address that has never connected to a volunteer opportunity before:
Volunteer First name
Volunteer Last name
Volunteer Zip code
Volunteer Country (default will be US)
Volunteer Phone number (Optional) will be shared with nonprofit, if provided
Volunteer Accepts VolunteerMatch Terms of Use (True)
Volunteer message to the nonprofit – optional for volunteer to complete
Display custom questions asked by the nonprofit – requested in the searchOpportunities query)
Display "Powered by VolunteerMatch" logo
Display "Agree to VolunteerMatch Terms of Use – and link to this URL.: https://www.volunteermatch.org/legal/terms.jsp
Connection Screen: Sample UI displaying Custom Questions, shifts and spots available per shift for an opportunity that limits number of connections
Following UI elements should appear on the connection confirmation screen
A Success message
Opportunity Title
Organization Name
Date & Time
Location or Virtual
"Powered by VolunteerMatch" logo
Connection Confirmation Screen: Sample UI
Top: Confirmation screen when volunteer has signed up for an opportunity that limits number of connections
Bottom: Confirmation screen when volunteer has expressed interest for an opportunity that doesn't limit number of connections 
Confirmation Email Sent to Volunteer – Managed by VolunteerMatch
Contains the same information as on the confirmation screen, and additionally the contact information for the volunteer coordinator at the nonprofit.
May include a custom email message to the volunteer from the nonprofit, if the VolunteerMatch Member feature is active.
May include an attachment from the nonprofit, if the VolunteerMatch Member features is active.
The email will be sent to the volunteer by VolunteerMatch, and it can be updated to include your logo.
Confirmation Email: Sample UI
Once your application has successfully connected volunteers to opportunities via the createConnection call, you may use VolunteerMatch’s getConnections call to retrieve reporting of the connections you’ve generated.
Connection information: Connection date, volunteer’s comments, answers to custom questions, shifts selected, the source that generated the connection. See full schema of Connection detail here. By default, VolunteerMatch only provides connection generated by your app. If you need data on connections generated from another source (i.e. VolunteerMatch hosted public site), your API key will need to have special configuration applied.
Volunteer’s information: email address, first and last name, zip code, skills etc. See full schema of Volunteer/Person detail here.
Opportunity details: Title, location, description, cause area etc. See full schema of Opportunity Detail here.
Organization details: Organization name, classification, ein, classification, cause area etc. See full schema of Organization Detail here.
Date Range: The date range of connections made. This parameter is always required.
Location: Use this parameter if you’d like to retrieve connection data based on opportunities' location. If an opportunity is virtual, its org’s location will be used to return connection data.
Opp ID: This parameter accepts VolunteerMatch’s opportunity ID. Use this parameter if you’d like to retrieve connections made for a single opportunity.
Org ID: This parameter accepts VolunteerMatch’s organization ID. Use this parameter if you’d like to retrieve connections made for opportunities that belong to a single organization.
Container name: This parameter accepts VolunteerMatch’s container name. Use this parameter if you’d like to get connections made for opportunities in organizations grouped under a container set up in VolunteerMatch. Containers are a special service offering (partially automated) that allows for grouping of opportunities by theme. Certain configuration to your API account/key applies.
Categories: This will allow you to get connections made for opportunities in specific cause areas. This parameter must be combined with Date Range and one other parameter.
Number of connections per page and page number: If you plan to display connections data on an UI that paginates, use these parameters to get connections data returned in pagination.
Sample UI 1: A list view of all connections made within a date range.
We suggest you display only the essential data for each connection and implement a View link that takes your user to a Detail page per connection --
.jpeg?version=1&modificationDate=1630444983198&cacheVersion=1&api=v2 "VolunteerMatch Open Network API > Best Practices for the VolunteerMatch Open Network Opportunities API > getConnections_API (Page 1).jpeg")
Sample UI 2: A detailed view of a single Connection.
We suggest you navigate user to this Detail page from a List view page per sample above.
.jpeg?version=1&modificationDate=1630445101037&cacheVersion=1&api=v2 "VolunteerMatch Open Network API > Best Practices for the VolunteerMatch Open Network Opportunities API > getConnections_API (Page 2).jpeg")
Please see our public repository in Github for sample code and getting started instructions.
All development and testing must be done on our stage environment (stage.volunteermatch.org) using a stage API Key.
Connections made in this environment will not be sent to our nonprofit partners and protects them from SPAM.
Note that our stage database contains test data, and is not representative of our live network. Testing or demoing connection functionality on production quality data can only be made using special systems. VolunteerMatch will provide this upon request when you are ready to release.
If a client key is NO longer active, the following response will be returned: 401 Your API key is inactive.