The goal of this document is to ensure that information provided by VolunteerMatch and our more than 130,000 nonprofit members is presented in a clear and consistent manner across applications. This document is divided into sections based on the most common API calls and pages in your application that present the data.
Search & Display of Opportunities
GraphQL Query = searchOpportunities
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.
UI Requirements – Search Results Page
Opportunity Title, which links to the Opportunity Detail page.
Images: VolunteerMatch can provide access to a repository of images.
Date and Time.
Location or Virtual.
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
UI Requirements – Opportunity Detail Page
Date and Time of opportunity.
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 ExpressInterest 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
Connecting a Volunteer to an Opportunity
GraphQL Mutation: createConnection
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
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.
Required Connection Data:
The following fields are required for ALL createConnection calls:
Volunteer email (primary key)
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
UI Requirements – Connection Screen
Volunteer message to the nonprofit – optional for volunteer to complete
Display custom questions asked by the nonprofit – requested in the searchOpportunities query)
Connection Screen: Sample UI displaying Custom Questions, shifts and spots available per shift for an opportunity that limits number of connections
Connection Confirmation Screen
Following UI elements should appear on the connection confirmation screen
A Success message
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
View or Display connections your application has made between volunteers and opportunities
GraphQL Mutation: getConnections
Once your application has successfully connected volunteers to opportunities via the createConnection call, you may use VolunteerMatch’s getConnections call to retrieve data based on the connections you’ve generated.
The getConnections call returns following information FOR EACH connection you’ve made --
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.
getConnections call accepts following query parameters --
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. 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.
Once you’ve retrieved connections data, if you would like to display or view them on an UI page, see below for sample UIs --
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 --
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.
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.