VolunteerMatch Opportunities API Guide
- Camden Olson
OUTDATED. PLEASE SEE THIS LINK FOR MOST RECENT DOCUMENTATION.
- 1.1 Introduction
- 1.2 Notes
- 2 Search Opportunities Using Filters
- 3 Display Matching Opportunities
- 4 Display Opportunity Details
- 4.1 Overview
- 4.2 API Field Reference
- 5 Create a Connection
- 6 Retrieve Connections (Optional)
- 7 How to Develop and Test
- 8 FAQs
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.
Logo can be downloaded here. Example below
Opportunity Connection Type Limitations
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.
Hide your API Key in Front-End Code
For security purposes, your API key should never be written in publicly-accessible front-end code. Please be sure to obscure the API key from the general public.
Search Opportunities Using Filters
Description: Provides functionality for potential volunteers to search for available opportunities.
The VolunteerMatch API offers access to nearly 100k opportunities at any given time. Use the searchOpportunities call to retrieve a list of available opportunities. To enhance the user experience, we recommend implementing additional filters to allow users to refine their search results and find their best opportunity match.
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)
searchOpportunities GraphQL Query Example
Example Call with required and recommended filters:
This query looks for opportunities with the following criteria:
Location: San Francisco, CA
Cause area: Animals
Great for: Groups, Done in a Day
Keywords: Dogs
Opportunity Type: In-person AND virtual
query {
searchOpportunities(
input: {
location: "san francisco"
categories: ["animals"]
greatFor: [groups, doneInADay]
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.
Pagination
For pagination or to load additional opportunities, make a subsequent searchOpportunities call with the same parameters and update the pageNumber field accordingly. This process will retrieve the next set of opportunities.
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)
For Each Opportunity Detail
Here is an example response from the searchOpportunities API in the OpportunitySearchResults object. You can extract and display the information from each opportunity as needed.
{
"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:
Comprehensive information about the opportunity.
A button allowing users to express their interest in the opportunity.
Time-Saving Approach
Instead of creating your own opportunity detail page, you can redirect users directly to the VolunteerMatch site using the url field. Note that this approach will not allow you to track the number of connections made through your API.
Example Opportunity Detail Page Display
The "Powered by VolunteerMatch" logo should be displayed on this page.
API Field Reference
OpportunityDetail Object (Link to OpportunityDetail Schema)
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:
The API Partner will verify the volunteer's email address
The API Partner will require the volunteer to agree to VolunteerMatch’s Terms of Use.
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.
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 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)
UI Requirements – Connection Screen
This modal can be divided into following sections:
Notification Text
Inform the volunteer that their information will be sent to the organization.
Information Collection
Display and collect any necessary information from the volunteer, including personal details and any additional questions that the organization may request.
Capture the Personal Details of the Volunteer
You will need to gather all the information required from the volunteer to create a connection.
For the volunteer information section, we recommend using free text input fields to capture personal details such as First Name, Email, Zip Code, and additional fields like Last Name, Phone Number, or Country.
Prompt the Volunteer to Answer Opportunity-Specific Questions
Some opportunities require specific questions to be answered before a connection can be made by the volunteer.
You can retrieve these questions (if any) using the
searchOpportunitiescall → opportunities → opportunity: OpportunityDetail object → customFields: List of CustomFieldDetail objects. Display them in the interest form for the volunteer to complete.
Consent Checkbox
A checkbox to inform the user that their information will be sent to VolunteerMatch and that they agree to the Terms of Use and Privacy Policy.
Submit Button
A button to complete the interest form. Pressing this button should call the
createConnectionAPI function.
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.
Once the connection is made, the volunteer will receive an email from VolunteerMatch confirming that the organization admin has been notified. The organization admin will also receive an email from VolunteerMatch with the volunteer’s contact information.
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
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)
Connection Confirmation Screen
Direct Connect Opportunities
There are some opportunities where we want to direct the user directly to a registration link provided by the nonprofit. You can identify these opportunities by the following criteria: redirectUrl is NOT NULL ANDconnection_type is NOT ‘passthrough.' For these opportunities, you still want to create the connection with the createConnection call, but then you should redirect the user to the redirectUrl. We suggest adding this redirect in the UI on the connection confirmation screen by letting the user know they need to complete registration at another site.
UI Requirements
A Success message
Opportunity Title
Organization Name
Date & Time
Location or Virtual
"Powered by VolunteerMatch" logo
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, 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.
This call provides detailed information about the connections users have made with VolunteerMatch opportunities. It can help you gather data on:
The total number of connections
The total number of connections within a specific timeframe
The number of people connected with opportunities in different cause areas
The total number of connections in a particular area
The total number of connections with a specific organization
And more!
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
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.
getConnections GraphQL Query Example
Example getConnections call
The following query retrieves the number of connections in California with the cause category “Animals” created in 2023.
API Field Reference
Connections Search Filters
GetConnectionsParamsInput (Links to GetConnectionsParamsInput Schema)
Connections Search Results
GetConnectionsResult (Links to GetConnectionsResult Schema)
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:
Initial Data Ingestion: Use the
searchOpportunitiesAPI call to fetch all VolunteerMatch opportunities with your need and ingest them into your catalog. This will populate your catalog with the current list of opportunities.Update Mechanism: Use the
searchOpportunities call with theupdateSincefilter field to retrieve opportunities that have been updated since your last request. Note that the searchOpportunities call will only return active opportunities.Scheduled Updates: Alternatively, you can set up a batch job to run daily. This job can fetch selected opportunities by their IDs and update their content in your catalog accordingly.
By implementing these methods, you can ensure that your catalog remains up-to-date with the latest opportunities from VolunteerMatch and your own site.