OLD - Best Practices for the VolunteerMatch Open Network Opportunities API

Owned by Samir shah (Unlicensed)
Last updated: Oct 08, 2024 by Camden Olson
6 min read

Overview

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.

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.

  • 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

UI Requirements – Opportunity Detail Page

  • 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

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

  • 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.

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

  • 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

Connection Confirmation Screen

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


Get reporting on 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 reporting of 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.

The 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. 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.

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.

 

How to Develop and Test

  • 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.