---
title: "Charities and selections"
description: "The charities of the Charitips catalog, the profiles they keep up to date, and the selections you build to offer them in your product."
canonical: https://www.charitips.com/docs/concepts/charities
---

# Charities and selections

> The charities of the Charitips catalog, the profiles they keep up to date, and the selections you build to offer them in your product.

Charitips works with a catalog of charities that keep their own profile up to date. You pick the ones your users choose from in a charities selection, and link it to your campaigns.

> **In short**
>
> - [List charities](https://www.charitips.com/docs/api-reference/list-charities.md) returns the catalog. Add `includeProfile=true` and a `locale` to get, with each charity, the profile to show your users.
> - A charity has one profile per country and language, plus an international one in English for some. The charity writes and updates them.
> - A selection groups the charities a campaign offers. Use one Charitips keeps up to date, or build your own.
> - A campaign cannot be activated without a selection.

## The catalog

[List charities](https://www.charitips.com/docs/api-reference/list-charities.md) pages through every charity, sorted by name. It answers 100 charities per page by default: pass `limit` and `cursor` to read them all, as explained in [Conventions](https://www.charitips.com/docs/api-reference/conventions.md#pagination). [Get a charity](https://www.charitips.com/docs/api-reference/get-charity.md) returns one. The catalog is also on [charitips.com](https://www.charitips.com/associations).

The `charity_publish` webhook event tells you when a new charity joins the catalog, and `charityprofile_update` when a profile changes. See [Webhooks](https://www.charitips.com/docs/webhooks/configuration.md).

## Profiles

A profile holds what your users read about a charity, written and kept up to date by the charity itself:

- its display name, a tagline, its purpose and a description of its actions;
- up to four key figures (`insights`);
- its logo, up to four cover images and a video;
- its website and social networks;
- its impact indicators, which tell what a given amount funds, such as a meal or a night of shelter.

### One profile per country and language

- A `COUNTRY` profile is written for one `country`, in its main language, and can speak of local actions. A French charity has one in French for France, often with a machine-translated copy in English (`isAutomaticallyTranslated: true`).
- An `INTERNATIONAL` profile, in English and without a `country`, is written for any reader and speaks of the larger cause.

### Reading profiles

- On [List charities](https://www.charitips.com/docs/api-reference/list-charities.md) and [Get a charity](https://www.charitips.com/docs/api-reference/get-charity.md), `includeProfile=true` adds the published profile in the `locale` you ask for, `fr` by default.
- [List charity profiles](https://www.charitips.com/docs/api-reference/list-charity-profiles.md) returns the profiles of every charity, and [Find all profiles](https://www.charitips.com/docs/api-reference/find-all-profiles.md) those of one, both filtered by `type`, `language` and `country`.

The charity itself also carries a name and a logo, copied from its profile in its home country. Show the profile: `Charity.name` is the legal name, the one printed on fiscal receipts, and may differ from the profile's display name.

The [charity selection widgets](https://www.charitips.com/docs/widgets/charity_selection.md) show the profiles for you. Build your own display when you need it, from the same data.

## Selections

A charities selection is the list of charities a campaign offers. Set its id as the campaign's `charitiesSelectionId`; without one, activating the campaign answers `400 No charity selection linked to this campaign`.

### Selections kept up to date by Charitips

These selections follow the catalog: a new charity that fits joins them on its own. [List charities selections](https://www.charitips.com/docs/api-reference/list-charities-selections.md) with `type=GENERIC` returns them.

| Selection                                                      | Sandbox id                             | Live id                                |
| -------------------------------------------------------------- | -------------------------------------- | -------------------------------------- |
| All charities                                                  | `42c71f3c-0012-446a-b835-d8bd76148e4b` | `8d1624cb-a67a-4752-81e6-586cf8dfa93c` |
| CSR highlights of the month, from the CSR calendar             | `d111eea8-04f1-4e58-8f03-4f60ebe9164f` | `517ef276-d637-43a1-8ac2-fcfd0de192c2` |
| Certified for transparency and impact by a trusted third party | `bbf94b55-bd06-46cd-897f-1366c5f63cc2` | `68c00182-2417-4d69-8ce5-ddf8af431847` |
| International, charities with an international profile         | `c6a1d6fe-1bb8-4167-89a2-07c4f8922039` | `049b9567-651f-4a9b-a7d5-f0d4d5a9c3cf` |
| 1% for the Planet                                              | `a2930322-8e8b-4f99-9f03-533ca4e1ea13` | `81a31dd3-ef6c-4556-8c8d-7047c52755af` |

### Your own selections

Create as many as you need, in the dashboard, where each charity's profile is shown, or with [Create a charities selection](https://www.charitips.com/docs/api-reference/create-charities-selection.md): a `name` (2 to 100 characters) and the `charityIds` from [List charities](https://www.charitips.com/docs/api-reference/list-charities.md).

```bash
curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout charities",
    "charityIds": [
      "<charityId>",
      "<charityId>",
      "<charityId>"
    ],
    "featuredCharitiesIds": [
      "<charityId>"
    ]
  }'
```

A few choices make a selection work:

- Offer at least six charities, so that each person finds one they care about.
- Cover several causes: your users do not all share the same concerns.
- Offer fewer in a small space, like a widget at checkout, where a long list slows the choice.

`featuredCharitiesIds` lists charities of the selection to highlight: the widgets show them first. A charity outside the selection answers `400 Featured charities must be part of the selected charities`, and a charity taken out of the selection stops being featured.

![Featured charities first in the widget](https://www.charitips.com/docs/img/featured.png)

Change a selection with [Update a charities selection](https://www.charitips.com/docs/api-reference/update-charities-selection.md): every campaign that uses it follows. Write to us for help choosing.

### Sharing a selection

- One selection can serve several campaigns.
- With account hierarchy, a child account's campaign can use a selection of your parent account, created with your credentials, or a generic one. A selection of another child account answers `400 Invalid charitiesSelectionId`. See [Account hierarchy](https://www.charitips.com/docs/concepts/account-hierarchy.md#campaigns-and-charities).

## Related

[Campaigns](https://www.charitips.com/docs/concepts/campaigns.md), [Charity selection widgets](https://www.charitips.com/docs/widgets/charity_selection.md), [Your first donation](https://www.charitips.com/docs/get-started/first-donation.md), [List charities](https://www.charitips.com/docs/api-reference/list-charities.md).