# Goodstack Services

# Introduction

Goodstack API allows you to build good into your product by facilitating charitable donations. We achieve this through the API's listed and specified in this documentation.

For all donations using the Goodstack API, Goodstack handles the vetting and validation of the good causes and onward the disbursement of the donation.

The Goodstack API is organised around REST. All API responses, including errors, return JSON and use standard HTTP response codes. In all API requests you must specify the content-type HTTP header as application/json. All API requests must be made over HTTPS.

# Authentication

Authenticate your API requests by setting your live secret API key in the Authorization header.

Two keys are provided to you, a publishable key prefixed with `pk_` and a secret key prefixed with `sk_`.

Publishable API keys are meant solely to identify your goodstack account. These can safely be published in places like your JavaScript code, or in an Android or iPhone app and are meant for usage with our SDKs.

Secret API keys should be kept confidential and only used in secure server environments.

Anywhere that accepts a Publishable key will also accept a Secret key, but routes marked to accept a Secret key will not accept a Publishable key.

# Formats

## IDs

All ID fields are case-sensitive. For example, `abc123` and `ABC123` are treated as different IDs.

## Dates

Dates are encoded as strings following the ISO 8601 standard `2025-08-01T12:00:00.000Z`.

## Pagination

A maximum of 100 objects can be returned per request and the limit can be specified by using the pageSize query parameter. By default, the pageSize is set to 25. A `_links` object is included in paginated responses, which contains `next` and `prev` URLs to retrieve the next or previous pages of results.  

## Monetary Values

Throughout the API, monetary values are encoded as integers representing the amount in the smallest currency unit, for example 100 cents for a donation of $1.00. Currency is encoded as a string following the ISO 4217 standard (e.g. `USD`).

## Errors

The API returns standard HTTP response codes to indicate success or failure of API requests. Errors may include a custom error message.
Error objects have these attributes, an `id`, a `message` corresponding to the HTTP response phrase of the error,
an optional `invalid-params` attribute detailing issues with the request.

An example error object returned from the API:
```json
{
  error: {
    code: 'bad_request',
    title: 'Bad request',
    message: 'Something is wrong with your request, please check any parameters and try again',
    reasons: ['amount is a required field']
  }
}
```

A summary of the HTTP status codes returned from the api is listed in the table below.

| Code        | Title           | Description  |
| ------------- |-------------| -----|
| 200      | Success | Request successful |
| 204      | No Content      |   Request successful with no content returned |
| 400 | Bad Request      | Request was invalid |
| 401 | Unauthorised | Authorization header is invalid |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource does not exist |
| 429 | Too Many Requests | Rate Limited |
| 500s | Internal Server Error | Something went wrong with the Goodstack API |


Version: v1

## Security

### PublishableApiKey

API key starting with 'pk_' that can be made public

Type: apiKey
In: header
Name: Authorization

### SecretApiKey

API key starting with 'sk_' that must be kept secure

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Goodstack Services](https://workplace-giving-docs.goodstack.io/_bundle/openapi.yaml)

## Employees

### List Workplace Giving Employee Profiles

 - [GET /v1/giving/profiles](https://workplace-giving-docs.goodstack.io/openapi/employees/paths/~1v1~1giving~1profiles/get.md)

## Donations

### List Donations

 - [GET /v1/giving/donations](https://workplace-giving-docs.goodstack.io/openapi/donations/paths/~1v1~1giving~1donations/get.md): Retrieve a list of donations.

## Donation Match Request

### List Donation Match Requests

 - [GET /v1/donation-match-requests](https://workplace-giving-docs.goodstack.io/openapi/donation-match-request/paths/~1v1~1donation-match-requests/get.md): Get a paginated list of Donation Match Requests

## Volunteering

### List Volunteering Opportunities

 - [GET /v1/volunteering/opportunities](https://workplace-giving-docs.goodstack.io/openapi/volunteering/paths/~1v1~1volunteering~1opportunities/get.md): Get a paginated list of Volunteering Opportunities

### List Volunteering Time Logs

 - [GET /v1/volunteering/time-logs](https://workplace-giving-docs.goodstack.io/openapi/volunteering/paths/~1v1~1volunteering~1time-logs/get.md): Get a paginated list of Volunteering Time Logs

### List Volunteering Opportunity Participants

 - [GET /v1/volunteering/opportunity-participants](https://workplace-giving-docs.goodstack.io/openapi/volunteering/paths/~1v1~1volunteering~1opportunity-participants/get.md): Get a paginated list of Volunteering Opportunity Participants

## Fundraising

### List Fundraisers

 - [GET /v1/fundraisers](https://workplace-giving-docs.goodstack.io/openapi/fundraising/paths/~1v1~1fundraisers/get.md): Get a paginated list of Fundraisers

## Gamification

### List Account Achievements

 - [GET /v1/gamification/account-achievements](https://workplace-giving-docs.goodstack.io/openapi/gamification/paths/~1v1~1gamification~1account-achievements/get.md): Get a paginated list of Account Achievements

## Campaigns

### List Campaigns

 - [GET /v1/giving/campaigns](https://workplace-giving-docs.goodstack.io/openapi/campaigns/paths/~1v1~1giving~1campaigns/get.md): Get a paginated list of Campaigns

## Budgets

### List Account Budget state changes

 - [GET /v1/giving/account-budgets/changes](https://workplace-giving-docs.goodstack.io/openapi/budgets/paths/~1v1~1giving~1account-budgets~1changes/get.md): This endpoint returns a list of all changes to an account's budget over time. Each entry represents the resulting budget state after a change occurred, along with the type of change that caused the update. The type of change is indicated by the type field.

## Donation Wallets

### List Donation Wallet state changes

 - [GET /v1/donation-wallets/changes](https://workplace-giving-docs.goodstack.io/openapi/donation-wallets/paths/~1v1~1donation-wallets~1changes/get.md): This endpoint returns a list of all state changes to a donation wallet's balance over time. Each entry represents the resulting wallet balance after a change occurred, along with the type of change that caused the update. The type of change is indicated by the type field.