Prize Draw Entries API

Enter members into a prize draw and look up their submissions from your own system — a CRM, e-commerce platform, POS or internal app. This surface is part of the Custom API (externalApi).

Typical uses: one entry per purchase, bonus entries for higher spend, or entering every customer who completes a sign-up or survey. The customer never fills in a form; your system decides who qualifies and sends the request.

Base URL

https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external

Authentication & permissions

Use a Bearer API key (inc_…):

Authorization: Bearer YOUR_API_KEY

Set up the integration

1. Log in to the Incentable Admin Dashboard and select the program that runs the prize draw (API keys are scoped to a single program).
2. Open Integrations and add (or open) a Custom API integration.
3. Under Permissions & Configuration → Prize Draws, confirm Read and Write are on. New Custom API keys have both on by default. Permission changes are made by Incentable — contact support if you need one changed.
4. Optionally choose a Default Prize Draw on the same card, so requests can omit prizeDrawId.
5. Generate the API key and store it securely.

Find the prize draw ID

Open the prize draw in the Admin dashboard, go to the Entries tab and click API. The Prize draw ID is shown with a copy button. The integration's settings page also has an Example body button next to the prize draw endpoint.

Enter a member

POST /prizedraws/entries

Request body

Also accepted: Idempotency-Key header. Resolution order: body idempotencyKey → header → externalRef.

Example

curl -X POST \
  "https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external/prizedraws/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prizeDrawId": "YOUR_PRIZE_DRAW_ID",
    "member": {
      "email": "jane@example.com",
      "firstname": "Jane",
      "lastname": "Doe",
      "accountKey": "CRM-100245"
    },
    "quantity": 2,
    "externalRef": "order-10045",
    "metadata": { "store": "Sydney CBD", "orderTotal": 129.95 }
  }'

Node.js example

const res = await fetch(
  "https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external/prizedraws/entries",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.INCENTABLE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prizeDrawId: process.env.PRIZE_DRAW_ID,
      member: { email: order.email, firstname: order.firstName, lastname: order.lastName, accountKey: order.customerId },
      quantity: Math.floor(order.total / 50), // e.g. one entry per $50 spent
      externalRef: `order-${order.id}`,
    }),
  }
);

const body = await res.json();
if (res.status === 201 || res.status === 200) {
  // Entered (201) or already entered on an earlier attempt (200)
} else if (res.status === 409 && body.code === "DUPLICATE_EXTERNAL_REF") {
  // This order was already entered — safe to treat as done
} else {
  console.error(res.status, body.code, body.message);
}

Make sure quantity is at least 1 — if your calculation can produce 0, skip the request rather than sending it.

Success response (201)

{
  "data": {
    "submissionId": "sub_1aae5cd95fe1b38bcedf",
    "prizeDrawId": "YOUR_PRIZE_DRAW_ID",
    "quantity": 2,
    "totalEntries": 5,
    "isTest": false,
    "externalRef": "order-10045"
  },
  "memberId": "memberDocId",
  "memberCreated": false,
  "message": "Entries created successfully"
}

A replay with the same idempotency key returns 200 with the original payload and adds no entries. A duplicate externalRef in the same prize draw returns 409 with the original submission id in details.submissionId. The same externalRef may be used in a different prize draw.

Behaviour notes

• Member upsert: accountKey → email → create a Pending member.
• Entry rules: the prize draw must be Active and inside its entry period. Per-member and per-submission limits from the prize draw settings apply, and excluded members are rejected. API requests cannot override limits; admins can add entries beyond a limit from the dashboard.
• Weighting: each entry is a separate ticket in the draw, so a member with 5 entries is five times as likely to win as a member with 1.
• Test mode: entries created while the prize draw is in test mode are tagged as test and only used in test draws. Turn test mode off before go-live.
• Email: if the prize draw's Entry received email is on, Incentable emails the entrant after each successful submission.
• Visibility: entries appear on the prize draw's Entries tab with source API. Every request — including rejected ones — is recorded in the integration's Activity log.

Common errors

Errors return a JSON body with error, message and code, and sometimes details.

4XX errors other than 429 will fail again if retried unchanged — fix the request rather than retrying. Retry 429 and 5XX with the same externalRef.

Look up a submission

GET /prizedraws/entries/{id}?prizeDrawId=YOUR_PRIZE_DRAW_ID

{id} may be the submissionId or your externalRef. prizeDrawId can be omitted when the integration has a default prize draw.

curl -X GET \
  "https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external/prizedraws/entries/order-10045?prizeDrawId=YOUR_PRIZE_DRAW_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": {
    "submissionId": "sub_1aae5cd95fe1b38bcedf",
    "prizeDrawId": "YOUR_PRIZE_DRAW_ID",
    "memberId": "memberDocId",
    "externalRef": "order-10045",
    "source": "api",
    "quantity": 2,
    "validEntries": 2,
    "voidEntries": 0,
    "isTest": false,
    "createdAt": "2026-10-20T00:15:00.000Z"
  }
}

voidEntries counts entries an admin has voided since the submission (for example, after a refund). Voided entries are not included in draws.

Test checklist

• Prize draw Active, inside its entry period, and in Test mode
• Custom API key has prizeDraws write (and read if you look up submissions)
• 201 on a first request; entries visible on the prize draw's Entries tab
• Same externalRef again returns 409, with no new entries
• Lookup by externalRef returns the submission
• Your system handles 422 rejections (closed, limit reached, excluded) without retrying
• Test mode turned off for go-live

Related guides

• Braze → Prize Draws — the same endpoint from a Braze campaign or Canvas
• API Overview — base URL, auth, getting your API key