Introduction

Introduction to our external API.

Authorization

In order to use this API, you must create a Personal Access Token and then pass an Authorization Header in your requests with the value Bearer {token}.

Create your Personal Access Token in Givecloud

  1. Log into your Givecloud Account
  2. Go to My Profile
  3. Scroll to Personal Access Tokens section
  4. Pick a name: API OAuth client creation
  5. On the next screen, you will get the randomly generated PAT string. Keep it somewhere safe as it is encoded and therefore we will not be able to retrieve it for you.

Compromised or Lost Token?

If you've lost your token or it's been compromised, you will want to revoke that token so that it can no longer be used to access the API.

Revoke Compromised / Lost Token

  1. Log into your Givecloud Account
  2. Go to My Profile
  3. Scroll to Personal Access Tokens section
  4. Click Revoke next to the token you'd like to remove

Rate Limits

The rate limiter restricts the number of API requests per minute as follows:

  • 60 requests per user or per IP for non-authenticated calls

If you send many requests in quick succession, you might see error responses with status code 429.

Handling limiting gracefully

Requests sent towards a limited endpoint will have X-RateLimit-Limit and X-RateLimit-Remaining headers. These headers instructs users on how to adjust their API usage before hitting the limit.

Another technique to handle limiting is to look for 429 Too Many Requests status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary.

Filtering results

To filter the lists of data in this API, you can use the filter query param along with the name of the parameter you'd like to filter.

As an example, if you'd like to filter the Contributions List based on the ordered_after filter which requires a date, you would do use the following syntax:

GET /admin/api/v2/contributions?filter[ordered_after]=2021-01-21

When filtering on dates, all dates must be in UTC format. You can also include the time, for example, 2021-01-21T13:00:00Z or 2024-03-01%2013:00. You can also pass a string representation of a date, for example, last sunday, -1 hour, last year, or first day of December 2023 and the API will convert it to the correct format.

Sorting results

The sort query parameter is used to determine by which property the results collection will be ordered. Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.

As an example, if you'd like to filter the Sponsees list based on the last_name property in descending order, you would do use the following syntax:

GET /admin/api/v2/sponsees?sort=-last_name