Quickstart

This page walks you from zero to a working API request in four steps.

1. Get your credentials

Every request to the ThirdSectorBee API needs a bearer token. There are two ways to get one.

Personal Access Token

Go to Account Settings → API Access → Generate token.

Use the token directly as your bearer token:

Authorization: Bearer <your-pat>

Personal Access Tokens are tied to your user account. They are best suited for small projects or personal scripts. If you are building an integration that will run on behalf of multiple users or as a production service, use OAuth instead.

OAuth client credentials

Register a client application via the Account API and use the OAuth 2.0 client credentials grant to obtain a token:

curl https://api.thirdsectorbee.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$TSB_CLIENT_ID \
  -d client_secret=$TSB_CLIENT_SECRET

The response includes an access_token to use as your bearer token. OAuth is the right choice for server-to-server integrations and any integration you ship to end users.

2. Make your first request

Every request also needs an X-Tenant-Id header — the identifier for your organisation in ThirdSectorBee, visible in your account settings.

curl https://api.thirdsectorbee.com/programmes \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID"

A successful response returns a JSON object with a list of results.

3. Read the response

List endpoints return a cursor-paginated envelope:

{
  "items": [
    { "id": "prog_01abc", "name": "Winter Appeal 2025", ... }
  ],
  "cursor": "eyJsYXN0S2V5IjoiMDFhYmMifQ"
}
  • items — the results for this page
  • cursor — an opaque token; pass it as a query parameter to fetch the next page. When cursor is absent you have reached the last page.

Fetch the next page:

curl "https://api.thirdsectorbee.com/programmes?cursor=$CURSOR" \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID"

The default page size is 50 items; pass limit (max 200) to change it.

4. Handle errors

All errors use the same envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Human-readable description"
  }
}

Common codes:

Code What it means
VALIDATION_ERROR The request body or parameters are invalid. Check the message for details.
NOT_FOUND The requested resource does not exist, or you do not have access to it.
UNAUTHORIZED Your token is missing, expired, or invalid.
FORBIDDEN Your token is valid but does not grant access to the requested organisation. Check your X-Tenant-Id header.
INTERNAL_ERROR Something went wrong on our side. Retry with exponential backoff.

Writes and reads

When you create or update a record (POST, PATCH, PUT, DELETE), the API returns 202 Accepted — not 200. The response body confirms the command was received:

{
  "id": "prog_01abc",
  "status": "accepted"
}

After a write, there may be a short delay before the change appears in list and search results. Build your integration to tolerate this: use the 202 response body to confirm success rather than immediately re-reading the record.

Debugging requests

Pass an X-Correlation-Id header on any request to trace it end-to-end:

curl https://api.thirdsectorbee.com/programmes \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID" \
  -H "X-Correlation-Id: my-request-123"

The same ID is echoed back in the response headers. On write requests, an X-Event-Id response header is also returned — useful for correlating a write with downstream processing if you need to investigate an issue.

What’s next

  • Authentication — full credential setup guide (PAT and OAuth)
  • Concepts — how async writes, eventual consistency, and tenant scoping work
  • API modules — pick an API and browse its full endpoint reference