Lucky Numbers#

This endpoint applies only to campaigns whose lucky-numbers mechanic runs in manual generation mode. In manual mode Evolu evaluates each entry and computes how many numbers the participant qualified for — but does not generate the numbers. You generate them and submit them back through this endpoint, where they become the participant's official lucky numbers.

Automatic generation mode

If the mechanic runs in automatic generation mode, Evolu generates the numbers itself and delivers them in the entry.evaluated webhook's outcome.numbers array — do not call this endpoint (it returns 422).

Submit lucky numbers#

POST/v1/entries/{entry_id}/lucky-numbers

Submit externally-generated lucky numbers

Submits the lucky numbers generated by the integrator for an entry. Only valid for campaigns whose lucky-numbers mechanic uses manual generation. The first accepted submission is final.

Request Body

Example

{
  "numbers": [
    {
      "series": "string",
      "order_number": "00000"
    }
  ]
}

{  "numbers": [    {      "series": "string",      "order_number": "00000"    }  ]}

Schema

numbersarrayrequired

The externally-generated lucky numbers for the entry.

numbers[].seriesstringrequired

Series identifier — a non-negative integer string.

numbers[].order_numberstringrequired

The number within the series — a digit string of exactly 5 digits (`00000` to `99999`).

Responses

201Lucky numbers assigned.

Example

{
  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "assigned_count": 0,
  "status": "assigned"
}

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "assigned_count": 0,  "status": "assigned"}

Schema

entry_idstring<uuid>required

assigned_countintegerrequired

Number of lucky numbers assigned.

statusstring

Submission result.

401Invalid or missing API key.

404Entry not found.

409Entry not yet evaluated, or numbers already submitted.

422Validation error (count mismatch, mode, duplicates...).

Headers#

Header	Required	Description
`Authorization`	yes	`Bearer <api_key>` — see Authentication.
`Content-Type`	yes	`application/json`

Path parameters#

entry_idstring<uuid>required

The entry to assign numbers to — the entry_id you received in the entry.received and entry.evaluated webhooks.

When to submit#

Wait for the entry.evaluated webhook. In manual mode its lucky-numbers outcome tells you exactly what to generate (and omits the numbers array that automatic-mode campaigns send):

{
  "mechanic_type": "lucky_numbers",
  "status": "APPROVED",
  "outcome": { "quantity": 5, "series_count": 10 }
}

{  "mechanic_type": "lucky_numbers",  "status": "APPROVED",  "outcome": { "quantity": 5, "series_count": 10 }}

quantity — how many {series, order_number} pairs to submit.
series_count — valid series values are 0 to series_count - 1.

Request structure#

numbersarrayrequired

The generated lucky numbers. The array length must equal the outcome.quantity from the entry.evaluated webhook. Each item:

numbers[].seriesstringrequired

The series — a non-negative integer string, 0 to series_count - 1.

numbers[].order_numberstringrequired

The number within the series — a digit string of exactly 5 digits, 00000 to 99999.

First submission is final

The first accepted submission for an entry is permanent. A second submission — even an identical one — is rejected with 409 Conflict. There is no overwrite.

Example request#

curl -X POST https://api.evolu.tec.br/v1/entries/01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8/lucky-numbers \
  -H "Authorization: Bearer evolu_live_aB3dE6gH_x7K2p..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      { "series": "0", "order_number": "12345" },
      { "series": "1", "order_number": "67890" }
    ]
  }'

curl -X POST https://api.evolu.tec.br/v1/entries/01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8/lucky-numbers \  -H "Authorization: Bearer evolu_live_aB3dE6gH_x7K2p..." \  -H "Content-Type: application/json" \  -d '{    "numbers": [      { "series": "0", "order_number": "12345" },      { "series": "1", "order_number": "67890" }    ]  }'

const response = await fetch(
  `https://api.evolu.tec.br/v1/entries/${entryId}/lucky-numbers`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${EVOLU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      numbers: [
        { series: '0', order_number: '12345' },
        { series: '1', order_number: '67890' },
      ],
    }),
  },
)

const response = await fetch(  `https://api.evolu.tec.br/v1/entries/${entryId}/lucky-numbers`,  {    method: 'POST',    headers: {      Authorization: `Bearer ${EVOLU_API_KEY}`,      'Content-Type': 'application/json',    },    body: JSON.stringify({      numbers: [        { series: '0', order_number: '12345' },        { series: '1', order_number: '67890' },      ],    }),  },)

import requests

response = requests.post(
    f"https://api.evolu.tec.br/v1/entries/{entry_id}/lucky-numbers",
    headers={
        "Authorization": f"Bearer {EVOLU_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "numbers": [
            {"series": "0", "order_number": "12345"},
            {"series": "1", "order_number": "67890"},
        ]
    },
)

import requestsresponse = requests.post(    f"https://api.evolu.tec.br/v1/entries/{entry_id}/lucky-numbers",    headers={        "Authorization": f"Bearer {EVOLU_API_KEY}",        "Content-Type": "application/json",    },    json={        "numbers": [            {"series": "0", "order_number": "12345"},            {"series": "1", "order_number": "67890"},        ]    },)

Response#

A successful submission returns 201 Created:

{
  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",
  "assigned_count": 2,
  "status": "assigned"
}

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "assigned_count": 2,  "status": "assigned"}

Errors#

Status	Cause
`401`	Missing or invalid API key.
`404`	Entry not found, or it belongs to another campaign / the other livemode.
`409`	The entry has not been evaluated for lucky numbers yet — wait for the `entry.evaluated` webhook.
`409`	Lucky numbers were already submitted for this entry.
`422`	The count does not match `outcome.quantity`; the mechanic is not in manual mode; the entry was rejected; a `series` is out of range; duplicate pairs in the request; or a number is already in use in the campaign.

Lucky numbers are unique per campaign: a (series, order_number) pair can be held by only one participant. Submitting a number already assigned elsewhere returns 422.