> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prizerail.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send entries

In a campaign where **Prizerail draws from entries**, your backend sends entrants to Prizerail as they enter. At each cutoff Prizerail locks the period's list, commits its fingerprint, and draws the winners from it with the random value, each entrant in proportion to their weight. You don't pick winners.

```http theme={null}
POST /api/v1/campaigns/{slug}/entries
Authorization: Bearer pr_…
Content-Type: application/json
```

```json theme={null}
{
  "entries": [
    "a1f9c2…",
    { "entrantId": "7be04d…", "weight": 3 },
    { "entrantId": "c55e18…", "displayName": "Ada", "avatarUrl": "https://…/ada.png" }
  ]
}
```

Each entry is either:

* a string, the entrant's id, or
* an object with `entrantId` plus an optional `weight`, `displayName` (up to 40 characters) and `avatarUrl` (https, up to 2,048 characters). The name and avatar show on the campaign page if they win.

Send up to 1,000 entries per request, and as many requests as you like. A drawing takes up to 100,000 entrants.

## Which draw an entry goes to

An entry goes to the drawing whose cutoff is next when it arrives. After a cutoff, new entries go to the following drawing. The response says which drawing they went to.

## Weight

`weight` is a whole number from 1 to 4,294,967,295, the entrant's number of entries. Leave it out and it's 1, so if you never send weights, every entrant has the same chance. An entrant with weight 3 is three times as likely to win as one with weight 1. Nobody wins twice in one draw.

## Sending again

Sending an entrant again before the cutoff sets their weight, name and avatar to what you sent, so a retry is always safe and you can send a running total. Sending them **without** a weight sets it back to 1, so if you use weights, always send them.

The response counts what happened:

```json theme={null}
{
  "drawing": { "id": "d7k2m9q4x1wz", "drawAt": "2026-10-17T01:00:00.000Z", "cutoffAt": "2026-10-17T00:45:00.000Z" },
  "added": 998,
  "updated": 1,
  "unchanged": 1,
  "count": 41203,
  "totalWeight": 58710
}
```

`count` and `totalWeight` are the drawing's totals so far.

## Checking what Prizerail has

```http theme={null}
GET /api/v1/campaigns/{slug}/entries?drawing={id}&limit=1000&after={next}
```

It returns the drawing's `count`, `totalWeight` and its `entries` in arrival order, the order the list locks in. Without `drawing`, it's the drawing taking entries now. Pass the response's `next` as `after` for the following page, until `next` is `null`. Each entry shows its `position` in the list once it has locked.

## Entrant ids

<Warning>
  Every locked list is published, hashed, so anyone can check a draw. Use an entrant id that can't be guessed or linked back to a person: an HMAC of your user id with a secret key, or a random id you store. A plain hash of a sequential or public user id can be reversed by trying ids. Keep the key fixed for the life of the campaign, and never use emails or usernames.
</Warning>

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `bad_request` | Not JSON, no entries or more than 1,000, a bad id, weight, name or avatar, or the same entrant twice in one request. |
| 404 | `not_found` | No such campaign under your account. |
| 409 | `not_entrants_campaign` | The campaign takes winners, not entries. |
| 409 | `campaign_ended` | The campaign has ended. |
| 409 | `no_open_drawing` | No drawing is taking entries, for example while the campaign is paused. |
| 409 | `not_taking_entries` | The campaign stopped taking entries while the request was in flight. |
| 409 | `too_many_entrants` | This request would take the drawing past 100,000 entrants. Nothing in it was stored. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.