---
title: "Create a vote"
description: "This vote will then have to be casted i.e linked to a Charity."
canonical: https://www.charitips.com/docs/api-reference/create-vote
---

# Create a vote

`POST /v1/votes`

This vote will then have to be casted i.e linked to a Charity.

**Authentication**: Bearer access token.

## Body

- `campaignId` (string, required, UUID): Id of the campaign
- `weight` (number, integer, minimum 1): An optional weight to assign to this vote. Weight affects campaign's buget distribution amongs charities. Vote with larger weight will direct a larger amount of the campaign's budget towards a charity than one with a lesser weight. This is only useful if you want some votes to have more weights than others.
- `externalId` (string): An optional internal id of your system e.g orderId or customerId. Can be used to link a donation to an entity in your system. Votes can be queried using this field.
- `uniqueExternalId` (string): Similar to externalId but should be unique across all votes. Can be used to prevent duplicate votes.
- `donor` (PartialDonor): Only required for EMAIL or SLACK campaigns. Attach useful user data to votes for a better usage tracking.
  - `street` (string): Address line 1
  - `streetAddition` (string): Address line 2
  - `city` (string): City
  - `country` (string): Country alpha 2 ISO code
  - `zip` (string): Zip code
  - `firstName` (string): Donor's first name
  - `lastName` (string): Donor's last name
  - `email` (string, email address): Donor's email.
  - `companyName` (string): Donor's company name.
  - `phone` (string): Donor's phone number.
  - `birthdate` (string (date))
  - `pictureUrl` (string, URL): Donor's phone number.
  - `title` (string): Donor's job title.
  - `personalEmail` (string, email address): Donor's personal email.
  - `persona` (string): Persona of the donor. One of `CSR`, `MARKETING`, `HR`, `SALES`, `COMMUNICATION`, `PRODUCT`, `SMB`, `OTHER`.
  - `extraInfo` (string): Additional information about the donor.
  - `externalId` (string): Optional id to link this donor to an entity on your side.
  - `uniqueExternalId` (string): Similar to externalId but should be unique across all donors. Can be used to prevent duplicate donors
  - `slackId` (string): Donor's slack id. Required for SLACK campaigns.
- `language` (string): Locale to be used to communicate with the donor. Default to the campaign's language value. One of `fr`, `en`.
- `sendingDate` (string (date-time)): Required for EMAIL and SLACK campaigns, when Charitips sends it to the donor.

## Response 201

- `voteId` (string, required)
- `weight` (number)
- `status` (VoteStatus, required) One of `PENDING`, `DONE`, `PROCESSED`.
- `secret` (string, required)
- `externalId` (string)
- `uniqueExternalId` (string)
- `castedAt` (string (date-time))
- `validatedAt` (string (date-time))
- `processedAt` (string (date-time))
- `billingStatus` (BillingStatus, required) One of `PENDING`, `BILLED`, `PAID`.
- `autoAssigned` (boolean)
- `sendingMode` (CampaignSendingMode, required) One of `MANUAL`, `EMAIL`, `PHYSICAL`, `SLACK`, `POSTAL`.
- `sendingDate` (string (date-time))
- `sendingStatus` (DonationSendingStatus, required) One of `PENDING`, `FAILED`, `DONE`.
- `lastReminderId` (string)
- `message` (string)
- `reminderMessage` (string)
- `from` (string)
- `language` (Language, required) One of `fr`, `en`.
- `sharedOn` (SocialNetwork) One of `LINKEDIN`, `INSTAGRAM`, `FACEBOOK`, `TWITTER`, `WHATSAPP`.
- `accountId` (string, required)
- `campaignId` (string, required)
- `charityId` (string)
- `transactionId` (string)
- `donorId` (string)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `Campaign is a FACE_VALUE one. Only donations can be created`: On a FACE_VALUE campaign, each person gives an amount: create a donation, not a vote. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Votes cannot be posted.`
- 400 `donor is required for EMAIL campaigns.`: EMAIL campaigns send the donation to someone: pass `donor` with at least `email` and `firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Both donor.email and donor.firstName are required for email campaigns`: Pass both `donor.email` and `donor.firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `donor is required for SLACK campaigns.`: SLACK campaigns send the donation in Slack: pass `donor` with `slackId` and `firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Both donor.slackId and donor.firstName are required for slack campaigns`: Pass both `donor.slackId` and `donor.firstName`. See https://www.charitips.com/docs/api-reference/create-donation.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.
- 400 `Bad Request`: The `campaignId` does not exist on your account and environment. Ids from the sandbox do not exist in production. 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 `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 `Campaign has to be activated first.`: Activate the campaign once it has its charities selection, then retry. See https://www.charitips.com/docs/api-reference/activate-campaign.md.
- 403 `Only recurring donations can be created for recurring campaigns.`: This campaign has a recurring frequency: create a recurring donation. See https://www.charitips.com/docs/api-reference/create-recurring-donation.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 `Unique constraint failed on uniqueExternalId`: A resource with this uniqueExternalId already exists: your previous call succeeded. Fetch it with the list endpoint filtered by uniqueExternalId (donations, votes, donors) instead of creating it again; for recurring donations, keep the id you received at creation. See https://www.charitips.com/docs/api-reference/list-donations.md.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/votes \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "<campaignId>",
    "uniqueExternalId": "employee_4410"
  }'
```

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

## Response example (201, placeholder values)

```json
{
  "voteId": "<voteId>",
  "weight": 1,
  "status": "PENDING",
  "secret": "<secret>",
  "externalId": "<externalId>",
  "uniqueExternalId": "<uniqueExternalId>",
  "castedAt": "<castedAt>",
  "validatedAt": "<validatedAt>"
}
```