Concepts

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 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 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. Get a charity returns one. The catalog is also on charitips.com.

The charity_publish webhook event tells you when a new charity joins the catalog, and charityprofile_update when a profile changes. See Webhooks.

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 and Get a charity, includeProfile=true adds the published profile in the locale you ask for, fr by default.
List charity profiles returns the profiles of every charity, and Find all profiles 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 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 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: a name (2 to 100 characters) and the charityIds from List charities.

POST /v1/charities-selections

1curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Checkout charities",6    "charityIds": [7      "<charityId>",8      "<charityId>",9      "<charityId>"10    ],11    "featuredCharitiesIds": [12      "<charityId>"13    ]14  }'

Built from the spec and the API code

Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

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

Change a selection with Update a charities selection: every campaign that uses it follows. Write to us for help choosing.

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.

Campaigns, Charity selection widgets, Your first donation, List charities.