The VolunteerHub Open API is a REST-based API that allows third-parties to access raw VolunteerHub data for the purposes of application integration. 

Getting Started

You can access the Open API resource page in your site by entering /openapi at the end of your site's URL (e.g., "YOURORG.volunteerhub.com/openapi").

  1. At the top of the resource page is an open API file you can use to create custom connectors with applications like Microsoft Flow.
  2. Lower on the page, use the interactive endpoint/parameter fields to build and test a query in the resource page without writing a single line of code.

Configuration

By default, only VolunteerHub "superusers" are configured for API access. This is typically sufficient for applications such as data synchronization, offline report generation, or control panels giving an overview of VolunteerHub activity. 

Any Superuser in a VolunteerHub site has access to the API free of charge, but we do not provide assistance in the configuration or maintenance of your use of this tool. 

Endpoints

All endpoint urls are formed by appending the relative url for the desired endpoint onto the secure sockets layer (SSL) url for the organization's VolunteerHub site. For example, if the VolunteerHub site is typically accessed using:

http://myorganization.volunteerhub.com

Then, its SSL url would be:

https://myorganization.volunteerhub.com

A list of events could then be retrieved via the url:

https://myorganization.volunteerhub.com/api/v1/events 

For a complete list of available endpoints, click here.

Note that SSL connections are required because of the use of basic authentication for user identification (see below). The API will not respond to non-SSL requests.

Authentication

User identification is provided by basic authentication over SSL, and therefore all requests must include a valid Authorization HTTP header. To compute the appropriate value for the Authorization header, use the following pseudo-code:

"basic " + Base64Encode(username + ":" + password)

For example, if the username is "jsmith" and the password is "1234" then you would include the following header with your request:

Authorization: basic anNtaXRoOjEyMzQ=

A detailed discussion of basic authentication is beyond the scope of this manual--please see Wikipedia as a starting point for further details.

HTTP compression

Because API responses are text-based and contain repetitive formatting, they are usually quite compressible. Because of this, HTTP compression can be employed to reduce the size of such responses by as much as 80%, greatly reducing transfer time and increasing performance. If your webservice client supports it (most do), you can enable HTTP compression by including the Accept-Encoding HTTP header in your request. For example, the following header will return the response using either gzip or deflate compression:

Accept-Encoding: gzip, deflate

Although highly recommended, HTTP compression is optional. If the Accept-Encoding header specified above is omitted, responses will be sent using standard uncompressed text.

Response format (JSON/XML)

Responses can be returned in either JSON or XML format. By default, responses are returned in JSON format; if this is the desired format then no further action is required. To receive responses in XML format, simply include the following Accept HTTP header with your request:

Accept: text/xml