Create a campaign

• name#stringrequired2 to 100 characters

  Name of your campaign. Only use for display in your dashboard.

• slug#string2 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.

  PRIVATEPUBLIC

• type#string

  Whether the campaign should be a permanent or time limited one.

  TIME_BASEDPERMANENT

• charitiesSelectionId#stringUUID

  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.

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

  FACE_VALUEDISTRIBUTION

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

  MANUALEMAILPHYSICALSLACKPOSTAL

• 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#string2 to 100 characters

  Will be displayed in the campaign page

• description#string2 to 1000 characters

  Will be displayed in the campaign page.

• titleColor#stringhex color

  Customize the color of titles in the campaign page

• accentColor#stringhex 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#stringURL

  Logo that will be displayed in the campaign page's header

• faviconUrl#stringURL

  Image that will be used as favicon for the campaign page

• message#string1 to 600 characters

  Slack campaigns only. Message posted to each participant with their donation. Supports the {{firstName}}, {{lastName}}, {{company}} and {{amount}} variables.

• reminderMessage#string1 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#stringUUID

  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.

  fren

• emailSenderName#string1 to 100 characters

  Email campaigns only. Name of the sender of the donation emails.

• emailSenderPictureUrl#stringURL

  Email campaigns only. Picture of the sender displayed in the donation emails.

• emailSubject#string1 to 100 characters

  Email campaigns only. Subject of the donation emails.

• emailTemplate#string1 to 1000 characters

  Email campaigns only. HTML body of the donation emails. Supports the {{firstName}}, {{lastName}}, {{company}} and {{amount}} variables.

• emailReplyTo#stringemail 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.

  CREATIONCLAIM

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

  Required in the spec, optional for the API.

• leadCollectionOptions#object

  Fields to be collected from the donor: any of the keys below, at least one. custom is your own question, or false.

  5 child fields

  • fullnameboolean

  • companyNameboolean

  • emailboolean

  • phoneboolean

  • customstring | false

• campaignTemplateId#stringUUID

  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.

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

  MANUALEMAIL

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

  SOCIAL_SHARINGDONATION_MATCHINGCHARITY_NEWSLETTER_SUBSCRIPTION

No field is described in the spec.

• campaignId#stringalways returned

• name#stringalways returned

• type#CampaignType

  TIME_BASEDPERMANENT

• amountType#CampaignAmountType

  FIXED_AMOUNTFREE_AMOUNT

• audienceType#CampaignAudienceType

  PRIVATEPUBLIC

• donationType#CampaignDonationType

  FACE_VALUEDISTRIBUTION

• givingType#GivingTypealways returned

  FINANCIALPAYROLLPAID_TIME_OFF

• recurringType#RecurringTypealways returned

  NONEFREQUENCYMANUAL

• startDate#string (date-time)always returned

• endDate#string (date-time)

• budget#integer (int64)

• sendingMode#CampaignSendingMode

  MANUALEMAILPHYSICALSLACKPOSTAL

• status#CampaignStatus

  DRAFTPENDINGACTIVECOMPLETECANCELED

• slug#string

• publicKey#stringalways returned

• withFiscalReceipts#booleanalways returned

• language#Language

  fren

• frequency#string

• budgetFrequency#string

• billingStatus#BillingStatusalways returned

  PENDINGBILLEDPAID

• defaultHideAmount#boolean

• withHideAmountCustomization#boolean

• withGiftCards#boolean

• withLeadCollection#boolean

• withoutCustomization#booleanalways returned

• momentType#MomentType

  OCCASIONKEY_MOMENTEDITION

• momentSlug#string

• leadCollectionOptions#object

• donationsBilledOn#DonationBilledOnalways returned

  CREATIONCLAIM

• withDonationsValidation#booleanalways returned

• fiscalReceiptType#FiscalReceiptTypealways returned

  YEARLYSINGLE_DONATION

• fiscalReceiptSendingMode#FiscalReceiptSendingModealways returned

  MANUALEMAIL

• defaultHasBeenCharged#booleanalways returned

• defaultFeeType#FeeTypealways returned

  EXCLUDEDINCLUDED

• donationValidityPeriod#stringalways returned

• template#string

• physicalFormat#PhysicalFormat

  CUSTOMPRINTPARCEL

• withEmailWall#boolean

• postDonationWidgets#PostDonationWidget[]always returned

• 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#stringalways returned

• campaignTemplateId#string

• donorPlatformId#string

• createdAt#string (date-time)always returned

• updatedAt#string (date-time)always returned

Errors

• 400 Bad Request
• Invalid charitiesSelectionId

  {
    "statusCode": 400,
    "message": "Invalid charitiesSelectionId",
    "error": "Bad Request"
  }

• Budget is required for FIXED_AMOUNT campaigns

  {
    "statusCode": 400,
    "message": "Budget is required for FIXED_AMOUNT campaigns",
    "error": "Bad Request"
  }

• INCLUDED fee type not supported

  {
    "statusCode": 400,
    "message": "INCLUDED fee type not supported",
    "error": "Bad Request"
  }

• Public campaigns must be both FIXED_AMOUNT and DISTRIBUTION campaigns

  {
    "statusCode": 400,
    "message": "Public campaigns must be both FIXED_AMOUNT and DISTRIBUTION campaigns",
    "error": "Bad Request"
  }

• DISTRIBUTION campaigns must also be FIXED_AMOUNT campaigns

  {
    "statusCode": 400,
    "message": "DISTRIBUTION campaigns must also be FIXED_AMOUNT campaigns",
    "error": "Bad Request"
  }

• givingTarget is only supported for fundraising campaigns

  {
    "statusCode": 400,
    "message": "givingTarget is only supported for fundraising campaigns",
    "error": "Bad Request"
  }

• Only one of <givingType> campaigns is supported

  {
    "statusCode": 400,
    "message": "Only one of <givingType> campaigns is supported",
    "error": "Bad Request"
  }

• A field is missing, has the wrong type, or is not part of the request schema.

  Every request with a body or query is validated.

  {
    "statusCode": 400,
    "message": [
      "amount must not be less than 1",
      "property foo should not exist"
    ],
    "error": "Bad Request"
  }

• 401 Unauthorized
• Unauthorized

  Missing, expired or invalid access token.

  {
    "statusCode": 401,
    "message": "Unauthorized"
  }

• 403 Forbidden
• Account not validated

  {
    "statusCode": 403,
    "message": "Account not validated",
    "error": "Forbidden"
  }

• Account closed

  {
    "message": "Account closed",
    "code": "ACCOUNT_CLOSED"
  }

• 409 Conflict
• Slug already used

  {
    "message": "Slug already used",
    "code": "slug_already_used"
  }