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

# Events

> Retrieve reward events, Gift After Purchase events, and push-notification widget data.

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

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

## Rewards 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/rewards/events`

Your Rewards performance data, filtered by event type and date range. The response shape follows `type` — see [Event Types](/integration/api-integration/event-types).

<ParamField query="type" type="string" required>
  One of `view`, `click`, `pageview`, `transaction`.
</ParamField>

<ParamField query="start_date" type="string" required>
  Start of the window, `YYYY-MM-DD`.
</ParamField>

<ParamField query="end_date" type="string" required>
  End of the window, `YYYY-MM-DD`.
</ParamField>

<ParamField query="format" default="json" type="string">
  `json` (default) or `csv`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --get "$BASE/api/v1/rewards/events" \
    -d "type=view" \
    -d "start_date=2026-01-01" \
    -d "end_date=2026-01-31" \
    -d "format=json" \
    --header "X-API-Key: $KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL(`${BASE}/api/v1/rewards/events`);
  url.search = new URLSearchParams({
    type: "view",
    start_date: "2026-01-01",
    end_date: "2026-01-31",
    format: "json",
  });

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

<ResponseExample>
  ```json 200-view-or-click theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "67dd795d86f2741c8842cbf1",
        "type": "view",
        "timestamp": 1737632793931,
        "host": "66fbd742051790c97a42284f",
        "userId": "79be2e40-b1ba-40d5-a28c-87f312f0aa1f",
        "customUserId": "a9796ca0-d5a1-4eca-95ec-31baf2782fce",
        "device": "mobile",
        "partnerName": "Tails.com",
        "partnerId": "62f0ec618152c98efaa88d2d",
        "position": 5,
        "placement": "all",
        "offerViewTimestamp": 1737632793931,
        "offerId": "63077e1fd151a6c99ff65477",
        "preview": false
      }
    ]
  }
  ```
</ResponseExample>

<Accordion title="Other response variants (pageview, transaction)">
  ```json 200-pageview theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "67dd7b9bb61a300da7261d14",
        "type": "pageview",
        "host": "644aa8264283a61d0189ab22",
        "timestamp": 1737632793931,
        "userId": "1daa5cad-c662-4957-8585-37b59cdfd541",
        "customUserId": "a9796ca0-d5a1-4eca-95ec-31baf2782fce",
        "preview": false
      }
    ]
  }
  ```

  ```json 200-transaction theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "1816282031",
        "referenceId": "67dd7b9bb61a300da7261d14",
        "type": "transaction",
        "status": "pending",
        "netCommission": 1.87,
        "validationDate": null,
        "transactionDate": 1742563200000,
        "offerId": "6668549895c8efca5ace48f1",
        "host": "644aa8264283a61d0189ab22",
        "timestamp": 1742562910605,
        "partnerId": "63f8aa1bd47e2e477dbf15c3",
        "userId": "6c51e0a1-5272-4ab8-ae9a-2b6c5e1cc6b5"
      }
    ]
  }
  ```
</Accordion>

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

## Gift After Purchase 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/gap/events`

The same contract as Rewards events, for your thank-you page placement. Identical parameters and payloads — the only field that differs is the absence of `preview`.

Parameters: `type`, `start_date`, `end_date` required; `format` optional (`json` / `csv`). See [Rewards events](#rewards-events) above for the full field breakdown.

<RequestExample>
  ```bash cURL theme={null}
  curl --get "$BASE/api/v1/gap/events" \
    -d "type=transaction" \
    -d "start_date=2026-01-01" \
    -d "end_date=2026-01-31" \
    --header "X-API-Key: $KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL(`${BASE}/api/v1/gap/events`);
  url.search = new URLSearchParams({
    type: "transaction",
    start_date: "2026-01-01",
    end_date: "2026-01-31",
  });

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

<ResponseExample>
  ```json 200-transaction theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "1816282031",
        "referenceId": "67dd7b9bb61a300da7261d14",
        "type": "transaction",
        "status": "pending",
        "netCommission": 1.87,
        "validationDate": null,
        "transactionDate": 1742563200000,
        "offerId": "6668549895c8efca5ace48f1",
        "host": "644aa8264283a61d0189ab22",
        "timestamp": 1742562910605,
        "partnerId": "63f8aa1bd47e2e477dbf15c3",
        "userId": "6c51e0a1-5272-4ab8-ae9a-2b6c5e1cc6b5",
        "customUserId": "a9796ca0-d5a1-4eca-95ec-31baf2782fce"
      }
    ]
  }
  ```
</ResponseExample>

## Rewards widget data

<span className="text-xs font-mono font-semibold bg-[#0B1B2B]/10 text-[#0B1B2B] dark:bg-[#0B1B2B]/40 dark:text-white px-2 py-1 rounded">POST</span> `/api/v1/rewards/push-notification`

Returns the `all` placement from your Rewards widget — the offer set to build a push notification around. Same fields as the [Offer object](/integration/api-integration/core-objects), plus a click-ready `url` and `socialProof` count.

No parameters. Returns `404` with `partner.not-found` if no widget is configured.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "$BASE/api/v1/rewards/push-notification" \
    --header "X-API-Key: $KEY" \
    --header "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `${BASE}/api/v1/rewards/push-notification`,
    { method: "POST", headers: { "X-API-Key": KEY } }
  );
  const { data } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "67dd795d86f2741c8842cbf1",
        "partner": "Advertiser",
        "partnerLogo": "https://…/logo.png",
        "ageRestricted": false,
        "terms": "Offer valid until stocks last.",
        "url": "https://example.com?location=…",
        "title": "50% Discount",
        "description": "Get 50% off selected products.",
        "image": "https://…/image.png",
        "squareImage": "https://…/square.png",
        "discountCode": "50%",
        "offerInfoButtonDescription": "Discount applies at checkout.",
        "offerDiscountCode": "SUMMER50",
        "offerDiscountCodeType": "availableAtCheckout",
        "hasMultipleCodes": false,
        "socialProof": "8763 Claimed"
      }
    ]
  }
  ```
</ResponseExample>

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