--- title: "Claim a donation" description: "Link a donation with a given Charity." canonical: https://www.charitips.com/docs/api-reference/claim-donation --- # Claim a donation `POST /v1/donations/{donationId}/claim` Link a donation with a given Charity. **Authentication**: Bearer access token. ## Parameters - `donationId` (string, required) ## Body - `charityId` (string, required, UUID): Id of the Charity to which the donation will be made. - `amount` (integer (int64), minimum 1): Donation amount in minor currency unit i.e cents if not provided on creation. - `lead` (LeadInfo) - `fullname` (string) - `companyName` (string) - `email` (string, email address) - `phone` (string) - `custom` (string) - `hasAcceptedTerms` (boolean, required) ## Response 200 - `donationId` (string, required) - `amount` (integer (int64)) - `externalId` (string) - `uniqueExternalId` (string) - `status` (DonationStatus, required) One of `PENDING`, `DONE`, `PROCESSED`, `CANCELED`. - `secret` (string, required) - `withFiscalReceipt` (boolean, required) - `hasBeenCharged` (boolean, required) - `claimedAt` (string (date-time)) - `validatedAt` (string (date-time)) - `processedAt` (string (date-time)) - `billingStatus` (BillingStatus, required) One of `PENDING`, `BILLED`, `PAID`. - `hideAmount` (boolean, required) - `billedOn` (DonationBilledOn, required) One of `CREATION`, `CLAIM`. - `autoAssigned` (boolean) - `expiryDate` (string (date-time)) - `sendingMode` (CampaignSendingMode, required) One of `MANUAL`, `EMAIL`, `PHYSICAL`, `SLACK`, `POSTAL`. - `sendingDate` (string (date-time)) - `sendingStatus` (DonationSendingStatus, required) One of `PENDING`, `FAILED`, `DONE`. - `externalSendingId` (string) - `lastReminderId` (string) - `message` (string) - `reminderMessage` (string) - `from` (string) - `language` (Language, required) One of `fr`, `en`. - `sharedOn` (SocialNetwork) One of `LINKEDIN`, `INSTAGRAM`, `FACEBOOK`, `TWITTER`, `WHATSAPP`. - `ptoType` (PaidTimeOffType, required) One of `NONE`, `PAID_TIME_OFF`, `WORKING_TIME_REDUCTION`. - `accountId` (string, required) - `campaignId` (string, required) - `charityId` (string) - `recurringDonationId` (string) - `transactionId` (string) - `donorId` (string) - `orderPlatformUserId` (string) - `usageId` (string) - `parentDonationId` (string) - `parentVoteId` (string) - `parentRecurringDonationId` (string) - `createdAt` (string (date-time), required) - `updatedAt` (string (date-time), required) ## Errors - 400 `Lead is required`: The campaign collects the donor's details at the claim: pass `lead` with the fields enabled in the campaign's `leadCollectionOptions` and `hasAcceptedTerms` set to true. See https://www.charitips.com/docs/api-reference/claim-donation.md. - 400 `Lead has to accept terms and conditions`: Set `lead.hasAcceptedTerms` to true once the person has accepted the terms. See https://www.charitips.com/docs/api-reference/claim-donation.md. - 400 `Invalid lead information`: A field enabled in the campaign's `leadCollectionOptions` (fullname, companyName, email, phone or custom) is missing from `lead`. See https://www.charitips.com/docs/api-reference/claim-donation.md. - 400 `Lead collection is not enabled for this campaign`: The campaign does not collect leads: remove `lead` from the claim, or create the campaign with `withLeadCollection` and `leadCollectionOptions`. See https://www.charitips.com/docs/api-reference/create-campaign.md. - 400 `A field is missing, has the wrong type, or is not part of the request schema.`: `message` lists every problem. Unknown fields are rejected, not ignored: remove them rather than sending extra data. See https://www.charitips.com/docs/api-reference/errors.md. - 401 `Unauthorized`: The access token is missing, expired or invalid. Create a new one with your client id and secret, send it as `Authorization: Bearer `, then retry once. Sandbox tokens only work on api.sandbox.charitips.com. See https://www.charitips.com/docs/get-started/authentication.md. - 403 `Campaign has ended.`: The campaign is COMPLETE or CANCELED: nothing can be created, claimed or cast on it any more. Use an active campaign. See https://www.charitips.com/docs/api-reference/list-campaigns.md. - 403 `Account not validated`: The account behind your credentials has not finished onboarding. Complete it in the dashboard, or contact us. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed. - 403 `Account closed`: The account behind these credentials is closed: no token is issued and every call is refused, reads included. Contact Charitips to reopen it. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed. - 403 `Forbidden`: Your credentials cannot perform this action on this resource. An id from another account never answers 403: it is treated as unknown, with a 404 in the path or a 400 `Bad Request` in the body or the query. See https://www.charitips.com/docs/api-reference/errors.md. - 404 `Not Found`: No resource with this id on your account and environment. An id that belongs to another account answers 404 too when it is in the path. Ids from the sandbox do not exist in production. See https://www.charitips.com/docs/get-started/sandbox.md. - 409 `Donation already claimed`: The donation is no longer waiting for a claim: it is already linked to a charity, by your previous claim or automatically, or it was canceled. Read the donation: `status` and `charityId` tell which. See https://www.charitips.com/docs/api-reference/get-donation.md. ## Example ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations//claim \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "charityId": "" }' ``` ```javascript const response = await fetch('https://api.sandbox.charitips.com/v1/donations//claim', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "charityId": "" }), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); const data = await response.json(); ``` ```python import os, requests response = requests.post( "https://api.sandbox.charitips.com/v1/donations//claim", headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"}, json={ "charityId": "" }, ) response.raise_for_status() data = response.json() ``` ## Response example (200, placeholder values) ```json { "donationId": "", "amount": 2000, "externalId": "", "uniqueExternalId": "", "status": "DONE", "secret": "", "withFiscalReceipt": false, "hasBeenCharged": false } ```