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

# Let Prizerail fetch winners

The usual way. Publish each drawing's winners at a URL and Prizerail fetches them before the cutoff, so there's nothing to call. Set the URL in the campaign's **Winners** section in the [partner portal](/getting-started/partner-portal).

Rather post the list yourself? See [Send winners](/api/send-winners).

## The URL

The URL can name the drawing with placeholders, filled in for each draw:

| Placeholder | Becomes |
| - | - |
| `{drawingId}` | The drawing's id |
| `{drawAt}` | The draw time in UTC, ISO 8601, URL-encoded |
| `{date}` | The draw date in the campaign's time zone, e.g. `2026-10-15` |

For example `https://api.acme.com/prizerail/{drawingId}`.

<Warning>
  `{date}` only tells draws apart on daily, weekly and monthly campaigns. An hourly campaign has 24 draws on one date, so use `{drawingId}` or `{drawAt}` there.
</Warning>

The URL must be https on a public host, with no redirects. Prizerail sends `Accept: application/json` and gives up after 8 seconds.

Prizerail doesn't sign its requests yet. If your list shouldn't be readable by anyone who finds the URL, put an unguessable token in the path, such as `https://api.acme.com/prizerail/8f3a2c…/{drawingId}`. The URL is stored like a secret and never shown publicly.

## The response

The same body the [send winners](/api/send-winners) endpoint takes, with the same rules: exactly the expected count, no repeats, names and avatars optional.

```json theme={null}
{ "winners": ["u_8f3a…", "u_27c1…", "u_b904…"] }
```

## When it's fetched

* Every 5 minutes in the 2 hours before each cutoff. The last fetch can be up to 5 minutes before the cutoff, so have the list final at least 10 minutes early.
* Until your draw has happened, return `404`, an empty list, or no `winners` key. Prizerail tries again.
* Nothing is stored until the full list is there.
* If the list changes before the cutoff, the newer one replaces the earlier one.
* At the cutoff the list locks, exactly as if it had been posted.

If the URL still errors in the last 5 minutes before the cutoff, Prizerail staff are alerted. A list that never arrives leaves the drawing flagged, and you can extend its cutoff in the portal and try again.

## Confirming it arrived

Read the drawing with the API. Once a fetch has succeeded, its `winners` holds your list:

```bash theme={null}
curl https://www.prizerail.com/api/v1/campaigns/acme-daily/drawings/d7k2m9q4x1wz \
  -H "Authorization: Bearer $PRIZERAIL_KEY"
```

An empty `winners` with `status` still `open` means nothing has been accepted yet. Once `status` is `locked`, `verification.winnersCommitment` is the fingerprint of the list that locked. See [Drawings](/api/drawings).


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