---
title: "Create a campaign"
description: "This newly created campaign will have to be activated before registering donations."
canonical: https://www.charitips.com/docs/api-reference/create-campaign
---

# Create a campaign

`POST /v1/campaigns`

This newly created campaign will have to be activated before registering donations.

**Authentication**: Bearer access token.

## Body

- `name` (string, required, 2 to 100 characters): Name of your campaign. Only use for display in your dashboard.
- `slug` (string, 2 to 100 characters): Slug of your campaign. Will be use in your generated page url.
- `audienceType` (string): Whether the campaign participants have to be authenticated or not. One of `PRIVATE`, `PUBLIC`.
- `type` (string): Whether the campaign should be a permanent or time limited one. One of `TIME_BASED`, `PERMANENT`.
- `charitiesSelectionId` (string, UUID): Id of the selection of charities to be used.
- `amountType` (string): Whether the campaign has a fixed or free budget. For a FREE_AMOUNT campaign, the amount will be billed based on usage i.e total amount of created donations. One of `FIXED_AMOUNT`, `FREE_AMOUNT`.
- `donationType` (string): Whether the donations will have a face value or if the budget will be distributed across the charities based on the number & weights of casted votes. One of `FACE_VALUE`, `DISTRIBUTION`.
- `startDate` (string (date)): Defaults to today
- `endDate` (string (date)): Required for time limited campaigns.
- `donationValidityPeriod` (string): A valid time interval matching the format 'X days' | 'X weeks' | 'X months' | 'X years'. Maximum 1 year. Define the validity period for donations. Upon creation, a donation's expiry date will be computed by adding this duration to the latest date between startDate and now. If endDate is set, the expiry date will be the earliest between the computed date and endDate.
- `budget` (integer (int64)): Required for FIXED_AMOUNT campaigns. It represents the total amount that will be donated to charities.
- `sendingMode` (string): Set to EMAIL or SLACK to let Charitips send the donations, or to POSTAL to have the cards printed and posted. One of `MANUAL`, `EMAIL`, `PHYSICAL`, `SLACK`, `POSTAL`.
- `momentSlug` (string): Card design among the ones Charitips validated, listed by list-card-designs. The cards (printed for POSTAL campaigns), the donation page and the emails take its colours. Defaults to the Charitips card.
- `title` (string, 2 to 100 characters): Will be displayed in the campaign page
- `description` (string, 2 to 1000 characters): Will be displayed in the campaign page.
- `titleColor` (string, hex color): Customize the color of titles in the campaign page
- `accentColor` (string, hex color): Customize the color of buttons in the campaign page
- `frequency` (string): ISO 8601 recurring time interval. Define the frequency for recurring donations. Only recurring donations can be created for this campaign.
- `budgetFrequency` (string): ISO 8601 recurring time interval. Assign a frequency to the budget which is reset at each occurrence of this time interval.
- `logoUrl` (string, URL): Logo that will be displayed in the campaign page's header
- `faviconUrl` (string, URL): Image that will be used as favicon for the campaign page
- `message` (string, 1 to 600 characters): Slack campaigns only. Message posted to each participant with their donation. Supports the {{firstName}}, {{lastName}}, {{company}} and {{amount}} variables.
- `reminderMessage` (string, 1 to 600 characters): Slack campaigns only. Message posted to remind the participants who have not chosen a charity yet. Supports the {{firstName}}, {{lastName}}, {{company}} and {{amount}} variables.
- `accountId` (string, UUID): Only required to link the created entity to a child account instead of the current one.
- `language` (string): Default locale to be used for this campaign to communicate with the donor. This can also be overriden on a donation/vote basis. One of `fr`, `en`.
- `emailSenderName` (string, 1 to 100 characters): Email campaigns only. Name of the sender of the donation emails.
- `emailSenderPictureUrl` (string, URL): Email campaigns only. Picture of the sender displayed in the donation emails.
- `emailSubject` (string, 1 to 100 characters): Email campaigns only. Subject of the donation emails.
- `emailTemplate` (string, 1 to 1000 characters): Email campaigns only. HTML body of the donation emails. Supports the {{firstName}}, {{lastName}}, {{company}} and {{amount}} variables.
- `emailReplyTo` (string, email address): Email campaigns only. Address the participants reply to.
- `emailDisplayCard` (boolean): Email campaigns only. Whether the donation emails show the donation card. Defaults to true.
- `donationsBilledOn` (string): By default donations are billed upon creation. Set to CLAIM to bill them only once they have been claimed i.e a charity has been selected. One of `CREATION`, `CLAIM`.
- `withDonationsValidation` (boolean): If enabled, donations or votes will have to be validated manually by calling the validate endpoint. This is useful for donations that require a moderation step before being marked as claimed.
- `isDraft` (boolean): If enabled, the campaign will be created as a draft and default fields will not be set.
- `leadCollectionOptions` (object): Fields to be collected from the donor: any of the keys below, at least one. custom is your own question, or false.
  - `fullname` (boolean)
  - `companyName` (boolean)
  - `email` (boolean)
  - `phone` (boolean)
  - `custom` (string | false)
- `campaignTemplateId` (string, UUID): Id of a campaign template to start from, see list-campaign-templates. Some settings of the template, such as its recurring type, are applied to the campaign.
- `fiscalReceiptType` (string): Whether fiscal receipts for this campaign's donations should be issued upon its closure or grouped with other donations in yearly fiscal receipts. One of `YEARLY`, `SINGLE_DONATION`.
- `fiscalReceiptSendingMode` (string): Restricted to B2C use cases. Set to EMAIL to let Charitips email their fiscal receipt to the donors who paid their donation (hasBeenCharged). With MANUAL, you send them yourself. One of `MANUAL`, `EMAIL`.
- `withFiscalReceipts` (boolean): Restricted to B2C use cases. Default value of withFiscalReceipt for the donations of this campaign. Set to false when no fiscal receipt should be issued for them.
- `defaultHideAmount` (boolean): Hide the donation amount from the participants on the campaign page and the donation cards.
- `withLeadCollection` (boolean): Collect the fields set in leadCollectionOptions from the participants when they choose a charity.
- `defaultHasBeenCharged` (boolean): Restricted to B2C use cases, and only set at creation. The donors pay every donation of the campaign with their own money, as with hasBeenCharged on each donation. Required for givingTarget.
- `givingTarget` (integer (int64)): Only used for fundraising campaigns. It represents the target amount to be raised.
- `postDonationWidgets` (string[]): Blocks shown after a donation on Charitips pages and widgets: social sharing, a top-up paid by the beneficiary and the charity newsletter subscription. All of them by default. One of `SOCIAL_SHARING`, `DONATION_MATCHING`, `CHARITY_NEWSLETTER_SUBSCRIPTION`.

## Response 201

- `campaignId` (string, required)
- `name` (string, required)
- `type` (CampaignType) One of `TIME_BASED`, `PERMANENT`.
- `amountType` (CampaignAmountType) One of `FIXED_AMOUNT`, `FREE_AMOUNT`.
- `audienceType` (CampaignAudienceType) One of `PRIVATE`, `PUBLIC`.
- `donationType` (CampaignDonationType) One of `FACE_VALUE`, `DISTRIBUTION`.
- `givingType` (GivingType, required) One of `FINANCIAL`, `PAYROLL`, `PAID_TIME_OFF`.
- `recurringType` (RecurringType, required) One of `NONE`, `FREQUENCY`, `MANUAL`.
- `startDate` (string (date-time), required)
- `endDate` (string (date-time))
- `budget` (integer (int64))
- `sendingMode` (CampaignSendingMode) One of `MANUAL`, `EMAIL`, `PHYSICAL`, `SLACK`, `POSTAL`.
- `status` (CampaignStatus) One of `DRAFT`, `PENDING`, `ACTIVE`, `COMPLETE`, `CANCELED`.
- `slug` (string)
- `publicKey` (string, required)
- `withFiscalReceipts` (boolean, required)
- `language` (Language) One of `fr`, `en`.
- `frequency` (string)
- `budgetFrequency` (string)
- `billingStatus` (BillingStatus, required) One of `PENDING`, `BILLED`, `PAID`.
- `defaultHideAmount` (boolean)
- `withHideAmountCustomization` (boolean)
- `withGiftCards` (boolean)
- `withLeadCollection` (boolean)
- `withoutCustomization` (boolean, required)
- `momentType` (MomentType) One of `OCCASION`, `KEY_MOMENT`, `EDITION`.
- `momentSlug` (string)
- `leadCollectionOptions` (object)
- `donationsBilledOn` (DonationBilledOn, required) One of `CREATION`, `CLAIM`.
- `withDonationsValidation` (boolean, required)
- `fiscalReceiptType` (FiscalReceiptType, required) One of `YEARLY`, `SINGLE_DONATION`.
- `fiscalReceiptSendingMode` (FiscalReceiptSendingMode, required) One of `MANUAL`, `EMAIL`.
- `defaultHasBeenCharged` (boolean, required)
- `defaultFeeType` (FeeType, required) One of `EXCLUDED`, `INCLUDED`.
- `donationValidityPeriod` (string, required)
- `template` (string)
- `physicalFormat` (PhysicalFormat) One of `CUSTOM`, `PRINT`, `PARCEL`.
- `withEmailWall` (boolean)
- `postDonationWidgets` (PostDonationWidget[], required)
- `title` (string)
- `description` (string)
- `logoUrl` (string)
- `faviconUrl` (string)
- `titleColor` (string)
- `accentColor` (string)
- `givingTarget` (integer (int64))
- `message` (string)
- `reminderMessage` (string)
- `emailSenderName` (string)
- `emailSenderPictureUrl` (string)
- `emailSubject` (string)
- `emailTemplate` (string)
- `emailReplyTo` (string)
- `emailDisplayCard` (boolean)
- `lastCustomerReminderId` (string)
- `charitiesSelectionId` (string)
- `accountId` (string, required)
- `campaignTemplateId` (string)
- `donorPlatformId` (string)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `Invalid charitiesSelectionId`: The selection does not exist on your account. List your selections, or create one. See https://www.charitips.com/docs/api-reference/list-charities-selections.md.
- 400 `Budget is required for FIXED_AMOUNT campaigns`: Set `budget`, in cents, when amountType is FIXED_AMOUNT. See https://www.charitips.com/docs/api-reference/create-campaign.md.
- 400 `INCLUDED fee type not supported`: `defaultFeeType` INCLUDED only works with `defaultHasBeenCharged: true`. Leave `defaultFeeType` out or set it to EXCLUDED. See https://www.charitips.com/docs/api-reference/create-campaign.md.
- 400 `Public campaigns must be both FIXED_AMOUNT and DISTRIBUTION campaigns`: A PUBLIC campaign is a vote on a fixed budget: set amountType FIXED_AMOUNT and donationType DISTRIBUTION, or keep it PRIVATE. See https://www.charitips.com/docs/api-reference/create-campaign.md.
- 400 `DISTRIBUTION campaigns must also be FIXED_AMOUNT campaigns`: A DISTRIBUTION campaign shares a fixed budget: set amountType to FIXED_AMOUNT and a budget. See https://www.charitips.com/docs/api-reference/create-campaign.md.
- 400 `givingTarget is only supported for fundraising campaigns`: `givingTarget` only applies when the donor pays: send `defaultHasBeenCharged: true`, or remove `givingTarget`. See https://www.charitips.com/docs/api-reference/create-campaign.md.
- 400 `Only one of <givingType> campaigns is supported`: The campaign template sets a giving type (PAYROLL or PAID_TIME_OFF), and your account already has a campaign of that type. Use the existing campaign instead of creating a second one. See https://www.charitips.com/docs/api-reference/list-campaigns.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 <accessToken>`, then retry once. Sandbox tokens only work on api.sandbox.charitips.com. See https://www.charitips.com/docs/get-started/authentication.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.
- 409 `Slug already used`: Another campaign of your account already uses this `slug`. Pick another one. See https://www.charitips.com/docs/api-reference/errors.md.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/campaigns \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout donations",
    "charitiesSelectionId": "<charitiesSelectionId>"
  }'
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Checkout donations",
    "charitiesSelectionId": "<charitiesSelectionId>"
  }),
});
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/campaigns",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
    json={
      "name": "Checkout donations",
      "charitiesSelectionId": "<charitiesSelectionId>"
    },
)
response.raise_for_status()
data = response.json()
```

## Response example (201, placeholder values)

```json
{
  "campaignId": "<campaignId>",
  "name": "<name>",
  "type": "PERMANENT",
  "amountType": "FREE_AMOUNT",
  "audienceType": "PRIVATE",
  "donationType": "FACE_VALUE",
  "givingType": "FINANCIAL",
  "recurringType": "NONE",
  "status": "DRAFT"
}
```