> ## 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.

# Charities

> Browse and search verified charities on Donate.gg

<Badge icon="shield" color="blue" shape="pill">
  Requires <span style={{ color: '#1D4ED8', fontWeight: '800' }}>core</span> scope
</Badge>

The charities endpoints let you browse the full network of verified non-profits on Donate.gg. Use charity IDs from these endpoints when creating configs.

## List charities

`GET /charities`

Returns a paginated list of verified charities with full metadata.

```bash theme={null}
curl https://www.donate.gg/api/v1/charities \
  -H "donate-api-key: YOUR_API_KEY"
```

**Query parameters**

| Parameter   | Type                  | Default | Description                                           |
| ----------- | --------------------- | ------- | ----------------------------------------------------- |
| `limit`     | integer               | `50`    | Results per page, max `200`                           |
| `cursor`    | string                | -       | Cursor from previous `pageKey` for next page          |
| `isEnabled` | `"true"` \| `"false"` | -       | Filter by enabled state. Omit to return all charities |

**Response**

```json theme={null}
{
  "pageKey": "next_cursor_string",
  "response": [
    {
      "id": "charity_abc",
      "slug": "red-cross",
      "name": "American Red Cross",
      "logo": "https://...",
      "website": "https://redcross.org",
      "mission": "To prevent and alleviate human suffering...",
      "address": "431 18th St NW",
      "city": "Washington",
      "state": "DC",
      "country": "US",
      "zipCode": "20006",
      "taxId": "53-0196605",
      "socials": {
        "blog": "https://blog.redcross.org",
        "twitter": "RedCross",
        "facebook": "redcross",
        "instagram": "redcross",
        "linkedin": "RedCross",
        "youtube": "redcross",
        "blogUrl": "https://blog.redcross.org",
        "twitterUrl": "https://x.com/RedCross",
        "twitterHandle": "RedCross",
        "facebookUrl": "https://facebook.com/redcross",
        "facebookHandle": "redcross",
        "instagramUrl": "https://instagram.com/redcross",
        "instagramHandle": "redcross",
        "linkedinUrl": "https://linkedin.com/company/redcross",
        "linkedinHandle": "RedCross",
        "youtubeUrl": "https://youtube.com/@redcross",
        "youtubeHandle": "redcross",
        "youtubeChannelId": "UC..."
      },
      "isEnabled": true
    }
  ]
}
```

**Social fields**

All social fields live under the nested `socials` object and are `string | null`.

| Field                                                                                                       | Notes                                                                                                       |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `blogUrl`, `twitterUrl`, `facebookUrl`, `instagramUrl`, `linkedinUrl`, `youtubeUrl`                         | Full profile or channel URLs                                                                                |
| `twitterHandle`, `facebookHandle`, `instagramHandle`, `linkedinHandle`, `youtubeHandle`, `youtubeChannelId` | Platform handles or IDs                                                                                     |
| `blog`, `twitter`, `facebook`, `instagram`, `linkedin`, `youtube`                                           | **Deprecated.** Kept for older clients. `blog` matches `blogUrl`. The rest match the matching handle field. |

***

## Search charities

`GET /charities/search`

Search charities by name or slug. Only **enabled** charities are returned. Paginated.

```bash theme={null}
curl "https://www.donate.gg/api/v1/charities/search?term=red+cross" \
  -H "donate-api-key: YOUR_API_KEY"
```

**Query parameters**

| Parameter | Type    | Default | Description                                  |
| --------- | ------- | ------- | -------------------------------------------- |
| `term`    | string  | -       | **Required.** Search term (non-empty)        |
| `limit`   | integer | `10`    | Results per page, max `50`                   |
| `cursor`  | string  | -       | Cursor from previous `pageKey` for next page |

**Response (200)** - same paginated charity shape as the list endpoint.

**Errors**

| Status | Code               | Description                                                |
| ------ | ------------------ | ---------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR` | Missing/empty `term` or term too short after normalisation |

***

## Get a charity by ID

`GET /charities/{charityId}`

Returns a single **enabled** charity by its ID with full metadata. Disabled charities return `404`.

```bash theme={null}
curl https://www.donate.gg/api/v1/charities/charity_abc \
  -H "donate-api-key: YOUR_API_KEY"
```

**Path parameters**

| Parameter   | Description      |
| ----------- | ---------------- |
| `charityId` | The charity's ID |

**Response (200)** - a single charity object in the same shape as items in the list endpoint.

**Error responses**

| Status | Code        | Description                                |
| ------ | ----------- | ------------------------------------------ |
| `404`  | `NOT_FOUND` | No enabled charity found with the given ID |