Instant Prize#

When a campaign's instant-prize mechanic runs in integrator-declared mode, you decide who wins — Evolu does not draw. You run the instant-win logic on your side and register the outcome here; Evolu records it as a compliance ledger entry and confirms it once the entry passes processing.

How a registered win is confirmed

The win is declared inside the entry itself — the instant_win block of POST /v1/entries — so it is recorded atomically with the entry, with no race. If the entry is later rejected during processing, the win is voided and you receive the usual entry.completed event. If the entry is approved, the win is confirmed and echoed back on the entry.evaluated webhook.

Register a win#

A win is registered by including an instant_win block in the entry payload — see the Entries reference. There is no separate "submit win" endpoint.

{
  "enrollment": { "...": "..." },
  "consent": { "...": "..." },
  "evidence": { "...": "..." },
  "instant_win": {
    "won": true,
    "prize_definition_id": "0190559e-cc00-7a00-bc00-1a2b3c4d5e6f"
  }
}

{  "enrollment": { "...": "..." },  "consent": { "...": "..." },  "evidence": { "...": "..." },  "instant_win": {    "won": true,    "prize_definition_id": "0190559e-cc00-7a00-bc00-1a2b3c4d5e6f"  }}

instant_win.wonbooleanrequired

Whether the participant won an instant prize.

instant_win.prize_definition_idstring<uuid>

The prize won — a prize id from the campaign's prize pool (list them with GET /v1/prizes). Required when won is true, and must be omitted when won is false.

List the prize pool#

GET/v1/prizes

List the campaign's prize pool

Returns the prizes configured for the campaign, scoped to the API key's mode (live or test). `current_stock` reflects the units still available.

Responses

200The campaign's prize pool.

Example

[
  {
    "id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
    "name": "string",
    "type": "string",
    "unit_value": 0,
    "initial_stock": 0,
    "current_stock": 0
  }
]

[  {    "id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",    "name": "string",    "type": "string",    "unit_value": 0,    "initial_stock": 0,    "current_stock": 0  }]

Schema

No documented fields.

401Invalid or missing API key.

Returns the campaign's prizes for the API key's mode (live or test). Use a prize id as the prize_definition_id when registering a win. current_stock is the number of units still available — a win decrements it, a revoke/reassign returns it.

Revoke a win#

POST/v1/entries/{entry_id}/instant-prize/revoke

Revoke an instant-win award

Revokes the instant-win award registered for an entry.

Request Body

Example

{
  "reason": "string"
}

{  "reason": "string"}

Schema

reasonunknown

Why the award is being revoked.

Responses

200Award revoked.

Example

{
  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "won": true,
  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "status": "string"
}

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "won": true,  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "status": "string"}

Schema

entry_idstring<uuid>required

wonbooleanrequired

prize_definition_idunknown

statusstringrequired

`pending` (declared, awaiting evaluation), `awarded`, `revoked`, or `declined`.

401Invalid or missing API key.

404Entry or award not found.

422Validation Error

reasonstring

An optional free-text note recorded with the revocation.

Marks the entry's instant-win award as revoked. Idempotent — revoking an already-revoked award succeeds.

Reassign a win#

POST/v1/entries/{entry_id}/instant-prize/reassign

Reassign an instant-win award

Atomically revokes an instant-win award and re-registers it — on the same entry with a different prize, or on a different (already-processed) entry.

Request Body

Example

{
  "target_entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8"
}

{  "target_entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8"}

Schema

target_entry_idunknown

The entry to move the win to. Omit to keep the same entry (a prize change only).

prize_definition_idstring<uuid>required

The prize for the reassigned win — a prize id from the campaign's pool.

Responses

200Award reassigned.

Example

{
  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "won": true,
  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "status": "string"
}

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "won": true,  "prize_definition_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "status": "string"}

Schema

entry_idstring<uuid>required

wonbooleanrequired

prize_definition_idunknown

statusstringrequired

`pending` (declared, awaiting evaluation), `awarded`, `revoked`, or `declined`.

401Invalid or missing API key.

404Entry or award not found.

409Target entry already has an award.

422Validation error (prize, target entry state...).

Atomically revokes an existing win and re-registers it — on the same entry with a different prize, or moved to a different (already-processed) entry.

target_entry_idstring<uuid>

The entry to move the win to. Omit to keep the same entry — then the call only changes the prize. A different target entry must belong to the same campaign and have finished processing.

prize_definition_idstring<uuid>required

The prize for the reassigned win.

Errors#

See Error Handling for the full list. Common cases:

Status	Cause
`401`	Missing or invalid API key.
`404`	Entry not found, in another campaign / the other livemode, or no award to revoke/reassign.
`409`	The reassign target already has an award.
`422`	The campaign has no integrator-declared instant-prize mechanic; `prize_definition_id` is missing on a win, or does not belong to the campaign; the reassign target has not finished processing.