API Setup and Troubleshooting

An API account functions as a bridge that allows clients to extract data or integrate their own systems with Volunteero’s platform. This enables automated data exchanges, customised workflows, and seamless interactions between external applications and Volunteero.

Here is how to create an API account within Volunteero:

Account Name: This can be anything but worth noting that if you plan on having different API accounts for different functions you should name in a way that you know what each account relates to.

Role: The API account role works similarly to your staff user roles, it restricts what the API can access. For most organisations and API use cases, you will likely want to set this as a “System Administrator” to ensure the account is not limited to any aspects of your Volunteero environment.

Group: Similar to the above point, this will restrict the volunteers and missions the API account can access. For most organisations and API use cases, you will likely want to leave this blank to ensure the account is not limited to any aspects of your Volunteero environment.

IMPORTANT: When you create an API account, Volunteer will display the Account ID and Account Key. This is the only time you will see your Account Key so it is important you take a note of this and store it safely.

Webhooks are automated notifications sent from one system to another when a specific event occurs. They allow real-time communication between applications without requiring constant manual checks or API requests.

Within Volunteero we offer a variety of event types, you will need to set up a webhook for each that you will need. Here are instructions on how to do so:

This means the API could not understand the request due to invalid input.

Examples include:

Sending malformed JSON.

Missing required fields in a request.

Using an incorrect data type (e.g., sending a string instead of a number)

Fix: Double-check the request format, parameters, and data types.

This means authentication is required, but it was missing or incorrect.

Examples include:

Missing an API key or access token.

Using an expired or incorrect authentication token.

Fix: Ensure the request includes valid authentication credentials.

403 Forbidden: The user does not have permission to access the resource

This means authentication was successful, but the user lacks necessary permissions.

Examples include:

Trying to access admin-only features with a basic user role.

Attempting to modify a resource without the required access rights.

Fix: Check the API account roles and permissions. If in doubt you should grant the API account system admin access with no groups selected.

This means the requested resource does not exist or the URL is incorrect.

Examples include:

The mission or volunteer or other Volunteero resource can not be found. It could have been deleted by a staff user.

Fix: Verify that the resource exists and check the API documentation for the correct endpoint.

This means the client is sending too many requests in a short period.

Fix: Implement rate-limiting strategies to abide by the below rate limits, such as exponential backoff or caching responses.

Per account rate limit - 60 requests per minute. If exceeded then requests from the account will be rejected with HTTP status code 429

IP address rate limit - 300 requests per 5 minutes. If exceeded your IP address will be temporarily blocked until it gets below the threshold

These errors occur when something goes wrong on the API provider's side.

500 Internal Server Error: There was an error on the server

This is a generic error indicating something went wrong on the Volunteero API's backend.

Fix: Firstly it is worth retrying either immediately or at a later date, if the issue persists please contact the team through the support chat.