| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
The VolunteerMatch Opportunities API enables you to access and display thousands of volunteer opportunities for your users. Users can search for these opportunities and express interest in specific ones. Once a volunteer expresses interest—or makes a “connection”—we facilitate communication between the volunteer and the nonprofit organization.
You can refer to VolunteerMatch to see how we help volunteers find opportunities.
Notes
VolunteerMatch Attribution
As you implement the VolunteerMatch API, please be sure to include recognition of your partnership with VolunteerMatch. The "Powered by VolunteerMatch" logo should be 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.
...
By default, shift opportunities and passthrough opportunities (provided by our partners) are omitted due to additional UI complexity. As a result, this documentation does not cover the shift-related and passthrough fields. If you are interested in including shift or passthrough opportunities, please contact us at support@volunteermatch.org.
...
Search Opportunities Using Filters
Description: Provides functionality for potential volunteers to search for available opportunities.
...
To optimize the retrieval time for search results, we recommend implementing pagination or a "load more" feature. Limit the number of opportunities returned in each request to a maximum of 25. You can control pagination and the number of results by using the pageNumber and numberOfResults fields.
...
UI Requirements – Search Filters
Location
In-Person or Virtual
Cause Areas
Great For Selections
Keywords
Additional Filters (optional)
Skills
Radius
API Field Reference
Opportunity Search Filters
OpportunitySearchParamsInput Object (Links to OpportunitySearchParamsInput Schema)
...
| Expand | ||
|---|---|---|
| ||
Additional filters can be found in the OpportunitySearchParamsInput Schema Documentation. |
searchOpportunities GraphQL Query Example
Example Call with required and recommended filters:
...
| Code Block | ||
|---|---|---|
| ||
query {
searchOpportunities(
input: {
location: "san francisco"
categories: ["animals"]
greatFor: ["groups"]
keywords: ["dogs"]
returnVirtualAndOnSiteOpps: true
pageNumber: 1
numberOfResults: 25
}
) {
currentPage
resultsSize
opportunities {
datePosted
dateRange {
endDate
endTime
ongoing
startDate
startTime
}
description
id
location {
city
postalCode
region
}
parentOrg {
name
url
}
title
url
}
}
}
|
...
Display Matching Opportunities
Overview
Once the user has provided filter criteria, the next step is to display a list of matching opportunities returned from the searchOpportunities API call.
...
The response from the initial searchOpportunities call will include all the necessary and recommended fields for display. Details of these fields are outlined below.
UI Requirements – Search Results Page
Opportunity Title, which links to the Opportunity Detail page.
Organization Name. Can link to the organization url.
Date and Time. Flexible Schedule if Ongoing.
Location or Virtual.
Opportunity Description.
Button, which links to the Opportunity Detail page.
(Optional) Images: VolunteerMatch can provide access to a repository of images.
Optional: requirements, age groups, cause area, date posted 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.
API Field Reference
Opportunity Search Result
OpportunitySearchResults Object (Link to OpportunitySearchResults Schema)
...
| Expand | ||
|---|---|---|
| ||
|
For Each Opportunity Detail
| Expand | ||
|---|---|---|
| ||
|
...
| Code Block | ||
|---|---|---|
| ||
{
"data": {
"searchOpportunities": {
"currentPage": 1,
"resultsSize": 4,
"opportunities": [
{
"datePosted": "2024-04-15",
"dateRange": {
"endDate": null,
"endTime": null,
"ongoing": true,
"startDate": null,
"startTime": null
},
"description": "<p>Help us save more precious furry lives by fostering a dog in your home in the San Fransico East Bay Area until he/she is adopted to a new loving family.</p>",
"id": 85896,
"location": {
"city": "Oakland",
"postalCode": "94621",
"region": "CA"
},
"parentOrg": {
"name": "Furry Friends Rescue",
"url": "https://www.volunteermatch.org/search/org23439.jsp"
},
"title": "Dog Foster Home - East Bay Area",
"url": "https://www.volunteermatch.org/search/opp85896.jsp"
},
{
"datePosted": "2024-04-09",
"dateRange": {
"endDate": null,
"endTime": null,
"ongoing": true,
"startDate": null,
"startTime": null
},
"description": "<p>Chaparral House is a Non-Profit Skilled Nursing Facility in Berkeley dedicated to providing excellent person-centered care to elders.</p><p>If you have a gentle, friendly dog companion that you would like to share with our elder residents--we'd love to talk with you!</p><p>We currently have openings for our lively pet visiting program; for dogs both small & large & in between! Service dogs are great--but not required---however a clean bill of health (including up to date of vaccinations) from your vet is.<br /><br />Please contact us if you are interested in helping out. We have volunteers here every day of the week but not during evening or night time hours. All volunteers are required to provide proof of COVID vaccination and a booster. At this time volunteers are also required to wear masks at our facility.</p>",
"id": 3795737,
"location": {
"city": "Berkeley",
"postalCode": "94702",
"region": "CA"
},
"parentOrg": {
"name": "Chaparral House",
"url": "https://www.volunteermatch.org/search/org70812.jsp"
},
"title": "Pet Visitors for Nursing Home Needed",
"url": "https://www.volunteermatch.org/search/opp3795737.jsp"
},
{
"datePosted": "2024-03-25",
"dateRange": {
"endDate": "2024-06-29",
"endTime": "12:00:00",
"ongoing": false,
"startDate": "2024-04-27",
"startTime": "10:00:00"
},
"description": "For the number of folks who visit, Point Isabel is remarkably clean and safe for both dogs and people due to the efforts of EBRPD Rangers and people like YOU!.<br /><br />Help keep it that way by joining us to pick up *stuff* (stray poops; trash) OR by lending a hand with weeding, while enjoying the views and the fun at the world's largest off-leash dog park (aka "Disneyland for Dogs.) <br /><br />Come for 15 minutes or the full two hours -- every weed pulled or piece of *stuff* picked up helps! Bring your own gloves and tools if you have them. PIDO volunteers and the park ranger may also have some you can borrow. And don't forget to ask about our Special Treats for very good dogs -and their owners!<br /><br />*Foxtails are noxious, invasive weeds that are dangerous to dogs. Join volunteers to pull foxtails and other weeds around high-traffic areas such as benches and picnic tables that rangers can't reach with power tools and mowers. Spring and summer intervention are particularly important to preventing foxtails from going to seed and spreading. <br /><br />Rain/muddiness cancels.",
"id": 2896398,
"location": {
"city": "Richmond",
"postalCode": "94804",
"region": "CA"
},
"parentOrg": {
"name": "POINT ISABEL DOG OWNERS AND FRIENDS",
"url": "null/search/org1061417.jsp"
},
"title": "Clean-Up Day at Point Isabel",
"url": "https://www.volunteermatch.org/search/opp2896398.jsp"
},
{
"datePosted": "2024-03-21",
"dateRange": {
"endDate": "2024-04-21",
"endTime": "12:00:00",
"ongoing": false,
"startDate": "2024-04-21",
"startTime": "10:00:00"
},
"description": "<strong>Celebrate Earth Day Weekend at Point Isabel Regional Shoreline! </strong>At this work party we'll add dirt around our growing oaks, redwoods, and pines, and fill in holes that could be tripping hazards. <br /><br /><strong>WHO's ORGANIZING THIS</strong>: East Bay Regional Park District (EBRPD) and Point Isabel Dog Owners (PIDO). <br /><br /><strong>WHERE</strong>: The large, flat meadow halfway between the parking lot at 1 Isabel Street,Richmond (near Mudpuppy's Tub and Scrub and the Sit and Stay Cafe) and the smaller parking lot at the end of Rydin Road.<br /><br />The field is bounded by Hoffman Channel at the north, the Bay Trail/USPS Distribution Center on the south, and has the East Bay hills will be to the east and the Golden Gate Bridge to the west. From either parking lot it's a five-minute walk.<br /><br />You won't be able to miss EBRPD's green pickup truck. IF YOU CROSS THE BRIDGE OVER HOFFMAN CHANNEL, YOU'RE GOING THE WRONG WAY.<br /><br /><strong>Parking is a challenge on weekends</strong>. Carpool if you can and give yourself time to find a spot. There are bike racks near Mudpuppy's (1 Isabel Street). Don't bike <em>*through*</em> Point Isabel...that's not allowed, for safety reasons.<br /><br /><strong>WHEN</strong>: Sunday, April 21, 10 to noon. Come for 15 minutes or the whole two hours, every bit helps!<br /><br /><strong>WHAT TO BRING:</strong> Your own water, and gloves and a shovel if you have them. Wheelbarrows, rakes, and hoes could be <strong><em>very</em></strong> handy, although the rangers will bring some. A hat and sunscreen are good.<br /><br /><strong>OTHER THINGS TO KNOW</strong>: Point Isabel has lots of off-leash dogs wandering around. Your friendly dog is welcome but bring water for it and a leash in case you need it.",
"id": 3495756,
"location": {
"city": "Richmond",
"postalCode": "94804",
"region": "CA"
},
"parentOrg": {
"name": "POINT ISABEL DOG OWNERS AND FRIENDS",
"url": "null/search/org1061417.jsp"
},
"title": "Earth Day Weekend: TLC for trees at Point Isabel",
"url": "https://www.volunteermatch.org/search/opp3495756.jsp"
}
]
}
}
} |
Display Opportunity Details
Overview
Each result in opportunities returned from the search result should link to an Opportunity Detail page. This page should include:
...
The "Powered by VolunteerMatch" logo should be displayed on this page.
API Field Reference
OpportunityDetail Object (Link to OpportunityDetail Schema)
| Expand | ||
|---|---|---|
| ||
|
...
| Expand | ||
|---|---|---|
| ||
|
Create a Connection
Overview
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:
...
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.
Display the Interest Form and Enable Users to Express Interest
We recommend partners implement a form or modal to collect and submit this information, improving the user experience. The form can collect information such as contact information, availability, and any additional requirements requested by the organization. Once the form is submitted, the createConnection call transfers the data to the organization's system for further action.
When a volunteer expresses interest in an opportunity, they should be connected to the organization seamlessly. A button on the previous page should link to a modal where the volunteer’s information is gathered and sent to the nonprofit admin.
Required Connection Data:
The following fields are required for ALL createConnection calls:
...
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)
UI Requirements – Connection Screen
This modal can be divided into following sections:
...
Connection Screen: Sample UI displaying Custom Questions, shifts and spots available per shift for an opportunity that limits number of connections
...
Creating the Connection
Now that you’ve gathered the required information, it’s time to create the connection and send the data back to VolunteerMatch using the createConnection call.
...
To achieve this, construct a ConnectionDetailInput object with the necessary fields. We recommend linking this call to the action of the volunteer clicking the button you added to confirm their interest in the opportunity.
createConnection GraphQL Query Example
Example createConnection call
| Code Block | ||
|---|---|---|
| ||
mutation {
createConnection(
input: {
comments: "VolunteerMatch is the best!"
replies: { id: 25493, values: ["Yes"] }
oppId: 258682
volunteer: {
acceptTermsAndConditions: true
email: "name@volunteermatch.org"
firstName: "Jane"
lastName: "Doe"
zipCode: "55555"
}
}
) {
volunteer {
id
}
}
}
|
API Field Reference
ConnectionDetailInput Object (Links to ConnectionDetailInput Schema)
| Expand | ||
|---|---|---|
| ||
|
Connection Confirmation Screen
UI Requirements
A Success message
Opportunity Title
Organization Name
Date & Time
Location or Virtual
"Powered by VolunteerMatch" logo
...
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, ask your partner manager for assistance.
Retrieve Connections (Optional)
Congratulations, you’ve set up the VolunteerMatch API! The final step is to retrieve information on the connections you’ve created using the getConnections call.
...
Note: We recommend that each company has its own API key. The getConnections call will only retrieve connections made with that specific API key. If multiple companies share the same API key, the data will be aggregated among all companies using that key.
UI Reference
Examples of interfaces you can build
...
We suggest you navigate user to this Detail page from a List view page per sample above.
...
getConnections GraphQL Query Example
Example getConnections call
...
| Code Block |
|---|
query {
getConnections(
input: {
categories: ["animals"]
dateRange: "2023-01-01 to 2023-12-31"
location: "CA"
numberOfResults: 20
pageNumber: 1
}
) {
resultsSize
}
}
|
API Field Reference
Connections Search Filters
GetConnectionsParamsInput (Links to GetConnectionsParamsInput Schema)
| Expand | ||
|---|---|---|
| ||
|
Connections Search Results
GetConnectionsResult (Links to GetConnectionsResult Schema)
| Expand | ||
|---|---|---|
| ||
|
How to Develop and Test
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.
FAQs
Why does my API call return a different number of opportunities than the same search on volunteermatch.org?
Depending on your API key, there may be some types of opportunities that are not delivered via the API. These discrepancies may be due to the following reasons:
"Passthrough" Connection Type Opportunities: Some opportunities from partner feeds redirect to different websites, such as Idealist. While these opportunities are visible on our public site, they are not shared via the API. If you would like access to these opportunities through the API, please contact VolunteerMatch support at support@volunteermatch.org.
Opportunities with Shifts: Your API key might have a constraint that prevents the retrieval of shift-related opportunities. To access these opportunities, you will need to have this constraint removed. Note that once this feature is enabled, additional UI adjustments may be necessary to support shift-related opportunities.
I have other opportunities native to my site, and I’d like to integrate VolunteerMatch opportunities with my other opportunities so they appear as one catalog. How can I do this?
You can integrate VolunteerMatch opportunities with your own opportunities by following these steps:
...