Concepts

Three things about the ThirdSectorBee API are worth understanding before you build an integration. None of them are unusual, but knowing them upfront will save you debugging time.

Writes are asynchronous

When you create or update a record, the API returns 202 Accepted — not 200 or 201:

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

This means the API has received and validated your request. The record will be available to read shortly. Use the 202 response body (which contains the record’s ID) to confirm a write succeeded — do not immediately re-read the record to check.

Read requests (GET) return 200 with the full record as normal:

{
  "id": "prog_01abc",
  "name": "Winter Appeal 2025",
  "status": "active"
}

Eventual consistency

After a write, there may be a short delay before the change appears in list and search results. If you write a record and immediately query the list endpoint, you may get the previous state.

Build your integration to tolerate this:

• Use the 202 response body to confirm success, not a follow-up read
• If your integration reads back a record that looks stale, wait a moment and retry
• Don’t treat a stale read as an error — it resolves quickly

Your tenant ID

Every request scopes to a single organisation using the X-Tenant-Id header. ThirdSectorBee is used by many organisations, and your credentials only grant access to the ones your account belongs to.

Find your tenant ID in Account Settings. It looks like a short alphanumeric identifier.

The most common cause of 403 Forbidden responses is passing the wrong tenant ID — either a typo, or an ID copied from a different environment (staging vs production). Double-check it matches the organisation you’re trying to access.

If your account belongs to multiple organisations (for example, a consultant working across clients), pass the ID of the specific organisation you want to act on in each request.