> ## 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 winners

> Post each drawing's winners to Prizerail from your backend before the cutoff.

If you'd rather call us than publish a URL, switch the campaign's **Winners** section to push in the partner portal, and your backend posts each drawing's winners before its cutoff. Posting to a pull campaign returns `409 pull_campaign`.

```http theme={null}
POST /api/v1/campaigns/{slug}/drawings/{id}/winners
Content-Type: application/json
```

```json theme={null}
{
  "winners": [
    "user-8231",
    { "winner": "user-4417", "displayName": "Ada", "avatarUrl": "https://…/ada.png" },
    "user-0092"
  ]
}
```

Send exactly as many winners as the drawing's `winnersExpected`. Each is either:

* a string, the winner's id, or
* an object with `winner` plus an optional `displayName` (up to 40 characters) and `avatarUrl` (https, up to 2,048 characters), shown on the campaign page.

The same winner can't appear twice in one list. **Order matters:** each winner's position is part of how their prize is decided.

The response is the drawing, with the winners filled in: `201` the first time, `200` after that.

## Replacing and retrying

| When | Sending again |
| - | - |
| Before the cutoff | Replaces the list. |
| After the cutoff, same list | Returns `200`. A retry is always safe. |
| After the cutoff, different list | Returns `409 locked`. |

Names and avatars aren't locked. Resend the same winners with new ones to update them at any time, even after the draw.

## No winners by the cutoff

A drawing with no winners at its cutoff is flagged and waits. Extend its cutoff in the partner portal, then send the list.

## Winner ids

<Warning>
  Winner ids are public in each draw's proof. Use opaque ids, such as your internal user id or a hash of it, not emails or usernames, since a guessable value can be checked against the proof.
</Warning>

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `bad_request` | Not JSON, the wrong number of winners, a repeated winner, or a bad name or avatar. |
| 404 | `not_found` | No such campaign or drawing under your account. |
| 409 | `locked` | The cutoff has passed and this list differs from the locked one. |
| 409 | `pull_campaign` | Prizerail fetches this campaign's winners from your URL. |
| 409 | `campaign_ended` | The campaign has ended. |


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