> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tyviso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Giveaways

> Retrieve giveaway flows, claim discount codes, and pull giveaway event history.

[← Back to API Integration](/integration/api-integration)

Requires an API key — see [Authentication](/integration/api-integration/authentication).

## Get giveaway flow

<span className="text-xs font-mono font-semibold bg-[#07C983]/15 text-[#15803D] dark:bg-[#07C983]/20 dark:text-[#07C983] px-2 py-1 rounded">GET</span> `/api/v1/giveaways/flow`

Everything needed to render a giveaway yourself: the flow's template, header copy, styling settings, and its offers. Pass a `user` and we record a `view` event for you.

<ParamField query="id" type="string" required>
  The flow ID to retrieve.
</ParamField>

<ParamField query="user" type="string">
  Your user identifier. When provided, a `view` event is tracked.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --get "$BASE/api/v1/giveaways/flow" \
    -d "id=123" \
    -d "user=user-123" \
    --header "X-API-Key: $KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL(`${BASE}/api/v1/giveaways/flow`);
  url.search = new URLSearchParams({
    id: "123",
    user: "user-123",
  });

  const res = await fetch(url, {
    headers: { "X-API-Key": KEY },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "id": "123",
      "name": "Summer giveaway",
      "template": 1,
      "headerTemplate": 2,
      "header": { "title": "", "description": "", "steps": [] },
      "settings": {
        "ctaLabel": "Claim now",
        "ctaColor": "#ffffff",
        "ctaBg": "#4AAEAB",
        "headerBg": "#ffffff",
        "headerTextColor": "#000000",
        "sectionTitles": []
      },
      "logo": "https://…/logo.png",
      "offers": [
        {
          "id": "69c667633181fd52275838c2",
          "partner": "Advertiser",
          "partnerLogo": "https://…/partner-logo.png",
          "terms": "T&Cs apply. While stocks last.",
          "title": "Free Gift",
          "description": "Get your giveaway.",
          "image": "https://…/image.jpg",
          "squareImage": "https://…/square.jpg",
          "heroImage": "https://…/hero.jpg",
          "offerInfoButtonDescription": "Limited time offer",
          "expiry": null,
          "schedule": null
        }
      ]
    }
  }
  ```
</ResponseExample>

**Flow object** — `id`/`name` identify the flow; `template`/`headerTemplate` are layout identifiers; `header` holds title, description and a `steps` array; `settings` carries CTA and colour overrides; `offers` are [Offer objects](/integration/api-integration/core-objects) with an added `heroImage`, plus `expiry` and `schedule` (ISO 8601 or null).

See [Errors](/integration/api-integration/errors) for error shapes.

## Claim a code

<span className="text-xs font-mono font-semibold bg-[#07C983]/15 text-[#15803D] dark:bg-[#07C983]/20 dark:text-[#07C983] px-2 py-1 rounded">GET</span> `/api/v1/giveaways/claim`

Claims an available discount code for a giveaway offer and returns it.

<ParamField query="user" type="string" required>
  The user identifier.
</ParamField>

<ParamField query="offer" type="string" required>
  The offer ID to claim a code from.
</ParamField>

<Info>
  **Frequency logic:** with no `frequency` set on the offer, a user can claim once, ever. With one set, they can claim once per window — `1week`, `1month`, `1year`.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --get "$BASE/api/v1/giveaways/claim" \
    -d "user=user-123" \
    -d "offer=123" \
    --header "X-API-Key: $KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL(`${BASE}/api/v1/giveaways/claim`);
  url.search = new URLSearchParams({
    user: "user-123",
    offer: "123",
  });

  const { success, data, message } =
    await (await fetch(url, {
      headers: { "X-API-Key": KEY },
    })).json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200-claimed theme={null}
  { "success": true, "data": { "code": "DEF456" } }
  ```
</ResponseExample>

<Accordion title="200 — not claimable (three possible outcomes)">
  Three outcomes come back as `200` with `success: false`: already claimed, still inside the frequency window, or no codes left. Surface the message to the customer.

  ```json theme={null}
  { "success": false, "message": "You have already claimed this offer" }
  ```

  ```json theme={null}
  { "success": false, "message": "You can claim again after 2026-04-07T00:00:00+00:00" }
  ```

  ```json theme={null}
  { "success": false, "message": "No available codes for this offer" }
  ```
</Accordion>

See [Errors](/integration/api-integration/errors) for error shapes.

## Giveaway events

<span className="text-xs font-mono font-semibold bg-[#07C983]/15 text-[#15803D] dark:bg-[#07C983]/20 dark:text-[#07C983] px-2 py-1 rounded">GET</span> `/api/v1/giveaways/events`

Views and claims for your giveaway flows. Paginated at 10,000 events per page, with a maximum seven-day window per request.

<ParamField query="type" type="string" required>
  `view` or `claim`.
</ParamField>

<ParamField query="start_date" type="string" required>
  ISO 8601 — `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ`.
</ParamField>

<ParamField query="end_date" type="string" required>
  Same format. Maximum seven days from `start_date`.
</ParamField>

<ParamField query="page" default="1" type="integer">
  Page number. Walk until `current_page` equals `last_page`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --get "$BASE/api/v1/giveaways/events" \
    -d "type=claim" \
    -d "start_date=2026-03-01" \
    -d "end_date=2026-03-07" \
    -d "page=1" \
    --header "X-API-Key: $KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL(`${BASE}/api/v1/giveaways/events`);
  url.search = new URLSearchParams({
    type: "claim",
    start_date: "2026-03-01",
    end_date: "2026-03-07",
    page: "1",
  });

  const { data, pagination } =
    await (await fetch(url, {
      headers: { "X-API-Key": KEY },
    })).json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200-claim theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "69c667643181fd52275838c5",
        "type": "claim",
        "timestamp": 1774879237696,
        "user": "user-123",
        "offer": "69c667633181fd52275838c2"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10000,
      "total": 1,
      "last_page": 1
    }
  }
  ```
</ResponseExample>

<Accordion title="200 — view">
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "69c667643181fd52275838c4",
        "type": "view",
        "timestamp": 1774879237696,
        "user": "user-123",
        "flow": "69c67a3b2e4eb05d94289b3c"
      }
    ]
  }
  ```
</Accordion>

See [Errors](/integration/api-integration/errors) for error shapes.