> ## Documentation Index
> Fetch the complete documentation index at: https://docs.donate.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Charity requests

> Find charities in official registers and request ones that are not on Donate.gg yet

If a charity your users want is not on Donate.gg, you can request it. Requests are checked against the charity's official register and then reviewed by the Donate.gg team before the charity is listed. A request never lists a charity on its own, and review has no fixed timeline.

The flow is:

1. [List the registers](#list-registers) you can request from.
2. [Search a register](#search-a-register) by charity name or registration number.
3. [Request](#request-a-charity) a result whose status is `requestable`.
4. [Check the status](#get-request-status) later, or watch the [listing feed](https://docs.donate.gg/api/charities.md#recently-listed-charities) for the new charity.

Registry data identifies an organization. It does not confirm tax-deductible donations, charitable purpose or endorsement.

## List registers

Public (API key optional)

`GET /charity-requests/registers`

Returns every country and register you can request from, with the registration number format each accepts. The example shows one of the registers.

```bash theme={null}
curl https://api.donate.gg/api/v1/charity-requests/registers
```

```json theme={null}
{
  "items": [
    {
      "id": "scotland",
      "country": "UK",
      "name": "Scotland",
      "source": {
        "name": "Office of the Scottish Charity Regulator",
        "url": "https://www.oscr.org.uk/about-charities/search-the-register/download-the-scottish-charity-register/"
      },
      "attribution": {
        "text": "© Crown Copyright and database right 2026. Contains information from the Scottish Charity Register supplied by the Office of the Scottish Charity Regulator and licensed under the Open Government Licence v3.0.",
        "url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
      },
      "registration": {
        "label": "Charity number",
        "example": "SC012345",
        "pattern": "[Ss][Cc] ?[0-9]{6}"
      },
      "refresh": "daily",
      "coverage": "Current entries on the Scottish Charity Register."
    }
  ]
}
```

| Register id | Country | Registration number |
| - | - | - |
| `united-states` | US | EIN, for example `12-3456789` |
| `england-wales` | UK | Main charity number, `1234567` |
| `scotland` | UK | SC number, `SC012345` |
| `northern-ireland` | UK | NIC number, `NIC100002` |
| `france` | FR | SIREN, `775672272` |
| `japan` | JP | 13-digit corporate number (法人番号). Public-interest associations and foundations: search by number only |
| `new-zealand` | NZ | CC number, `CC21860` |
| `norway` | NO | Nine-digit organisation number, `864139442` |
| `netherlands` | NL | Nine-digit RSIN, `003014022` (not a KVK number) |
| `canada` | CA | Full charity number, `119219814RR0001` |
| `australia` | AU | Eleven-digit ABN, `50 169 561 394` |

`refresh` is `live` when the register is read for each search, or `daily` when Donate.gg uses a daily copy of the official dataset. When you show register data to users, show the register's `attribution` too.

## Search a register

Public (API key optional)

`GET /charity-requests/search`

Searches one register by charity name or registration number and returns up to 10 results. Searching never requests or lists a charity.

```bash theme={null}
curl "https://api.donate.gg/api/v1/charity-requests/search?register=scotland&term=food%20bank"
```

**Query parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `register` | string | Yes | Register id from [List registers](#list-registers) |
| `term` | string | Yes | Charity name or registration number, up to 120 characters |

```json theme={null}
{
  "items": [
    {
      "register": "scotland",
      "country": "UK",
      "registration": "SC000001",
      "name": "Example Food Bank",
      "logo": null,
      "website": "https://example.org/",
      "mission": null,
      "city": null,
      "state": null,
      "status": "requestable",
      "eligibilityIssues": [],
      "charity": null
    }
  ]
}
```

| `status` | Meaning |
| - | - |
| `listed` | Already on Donate.gg. `charity` has its `id` and `slug` for configs. |
| `requested` | A request already exists. |
| `requestable` | Can be requested. |
| `ineligible` | The register entry cannot be requested. `eligibilityIssues` explains why. |
| `unavailable` | The charity is disabled or has opted out and cannot be requested. |

## Request a charity

API key required

`POST /charity-requests`

Checks the registration against the official register, then saves a request for review. Repeating a request is safe: it is counted as more demand and does not undo a review decision.

```bash theme={null}
curl -X POST https://api.donate.gg/api/v1/charity-requests \
  -H "donate-api-key: $DONATE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"register": "scotland", "registration": "SC000001"}'
```

**Body**

| Field | Type | Description |
| - | - | - |
| `register` | string | Register id |
| `registration` | string | Registration number in the format the register accepts (32 max) |

A UK number must be from the register you name: `SC` numbers are Scottish, `NIC` numbers are Northern Irish, and plain numbers are England and Wales. Northern Ireland numbers may omit the `NIC` prefix.

The response is always `200`, with a `status`:

```json theme={null}
{
  "register": "scotland",
  "registration": "SC000001",
  "status": "requested",
  "charity": null
}
```

| `status` | Meaning |
| - | - |
| `listed` | Already on Donate.gg; nothing was requested. `charity` has its `id` and `slug`. |
| `requested` | The request is now waiting for review. |
| `already_requested` | A request was already waiting for review; this one was counted. |
| `needs_info` | Reviewers need more information. The request was not reopened. |
| `reviewed` | The request was reviewed and closed without a listing. It was not reopened. |

**Errors**

| Status | `code` | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | The body is missing a field or uses an unknown register |
| `400` | `INVALID_REGISTRATION` | The number is malformed or belongs to a different register |
| `404` | `REGISTRATION_NOT_FOUND` | The register has no current entry with this number |
| `422` | `NOT_ELIGIBLE` | The entry exists but cannot be requested (for example, removed) |
| `409` | `CHARITY_UNAVAILABLE` | The charity is disabled or has opted out |
| `409` | `NEEDS_MANUAL_REVIEW` | Another registration of the same organization needs review first |
| `429` | `RATE_LIMIT_EXCEEDED` | The request budget is used up; see `Retry-After` |
| `503` | `PROVIDER_UNAVAILABLE` | The register could not be checked. Retry later. |

Every error body has `error` (a message you can show) and `code`.

## Get request status

Public (API key optional)

`GET /charity-requests/{register}/{registration}`

Reports whether a registration is listed or requested. It reads Donate.gg only; it does not check the register or create a request.

```bash theme={null}
curl https://api.donate.gg/api/v1/charity-requests/scotland/SC000001
```

```json theme={null}
{
  "register": "scotland",
  "registration": "SC000001",
  "status": "requested",
  "charity": null,
  "queue": { "ahead": 2, "typicalSeconds": 180 }
}
```

`status` is `listed`, `requested`, `needs_info`, `reviewed` or `not_requested`. An invalid number, or one from another register, returns `400 INVALID_REGISTRATION`.

While `status` is `requested`, `queue` estimates where the request stands; otherwise it is `null`:

| Field | Meaning |
| - | - |
| `ahead` | Requests waiting for review that were submitted before this one |
| `typicalSeconds` | Typical seconds from submission to listing for recent requests, or `null` without enough recent history |

Both are estimates. Review order and timing are not guaranteed, and a request can still need more information or close without a listing.

## Rate limits

Register search and requests spend their own budgets in addition to the [normal API rate limit](https://docs.donate.gg/developer/rate-limits.md):

| Caller | Searches | Requests |
| - | - | - |
| API key (per project) | 120 per minute | 60 per hour |
| Anonymous (per client IP) | 30 per minute | Not available |

The anonymous search budget is shared with charity search on donate.gg. A ceiling across all callers can also apply when the registers are busy. An exhausted budget returns `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. Listing registers and checking status use only the normal limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.