Send winners

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.

POST /api/v1/campaigns/{slug}/drawings/{id}/winners
Content-Type: application/json

{
  "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

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.

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.

Getting started

API reference

Campaigns

Verification

Replacing and retrying

No winners by the cutoff

Winner ids

Errors

​Replacing and retrying

​No winners by the cutoff

​Winner ids

​Errors

Replacing and retrying

No winners by the cutoff

Winner ids

Errors