# Getting Started

Two ways to get started with OneHazel:

| Path | Best For | Start Here |
|---|---|---|
| **A — In-app onboarding** | Non-technical operators, fast setup via UI | [App Onboarding Guide](/app-onboarding) |
| **B — API-first** | Developers integrating programmatically | Continue below |

This guide covers **Path B** — making your first API calls with `curl`. If you'd rather click through the onboarding wizard in your dashboard, follow the [App Onboarding Guide](/app-onboarding) instead.

## Prerequisites

- A OneHazel operator account (sign up at [app.onehazel.com](https://app.onehazel.com))
- Your account must be approved by an admin (you'll receive an email when ready)
- `curl` or any HTTP client

## Step 1: Get your API key

You can create an API key from the dashboard (Settings > API Keys) or via the API.

### Via the API

```bash
curl -X POST https://api.onehazel.com/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "operatorId": "your-operator-id",
    "label": "My first key"
  }'
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key": "oh_live_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "label": "My first key",
    "createdAt": "2026-04-06T12:00:00.000Z"
  }
}
```

::: warning
Save your API key immediately. It is only shown once and cannot be retrieved later. Keys are stored as SHA-256 hashes.
:::

## Step 2: Configure your data template

Before sending data, tell OneHazel what type of data you will be sending. For iGaming operators, use the built-in `tpl_igaming` template.

```bash
curl -X PUT https://api.onehazel.com/operator-data-api/settings \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_igaming"
  }'
```

**Response:**

```json
{
  "success": true,
  "message": "Settings updated"
}
```

The iGaming template defines entity types (player, operator, game), event types (transaction, game_activity, session, bonus, block, support, affiliate), state keys (balance, kyc_status, risk_score, loyalty_tier), and PII fields that are automatically encrypted.

## Step 3: Send your first entity

Create a player entity with some basic data.

```bash
curl -X POST https://api.onehazel.com/operator-data-api/entities \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "player",
    "externalId": "player_12345",
    "data": {
      "first_name": "James",
      "last_name": "Wilson",
      "email": "james.wilson@example.com",
      "country": "GB",
      "currency": "GBP",
      "date_of_birth": "1992-03-15",
      "registration_date": "2026-04-06T10:30:00Z",
      "status": "active"
    }
  }'
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "ent_a1b2c3d4e5f67890",
    "externalId": "player_12345",
    "entityType": "player",
    "action": "created"
  }
}
```

Fields like `first_name`, `last_name`, and `email` are automatically encrypted at rest because they are defined as PII fields in the iGaming template.

### Capturing affiliate attribution?

If your players arrive via affiliate or ad-platform links (ReferOn, Affise, Income Access, Google Ads, Meta Ads, TikTok Ads, etc.) the **affiliate tracking parameters in the landing URL must reach OneHazel on the player ingest call** — otherwise affiliate platforms reject your daily reports as malformed and affiliates don't get paid.

The [OneHazel Affiliate Tag](/connectors/attribution-tag) is a 30-second install — one `<script>` line — that captures `mid`, `fluid`, `gclid`, `fbclid`, `utm_*`, and similar params from the landing URL into a first-party cookie. Your registration handler reads them via `window.OneHazel.getAttribution()` and threads them into the player payload above.

```html
<script src="https://app.onehazel.com/tag/v1/oh.js" data-operator-id="op_xxxxxxxx"></script>
```

Skip this if your stack already captures URL params server-side and you can include them in the `data` block yourself.

## Step 4: Record an event

Now record a transaction event for the player.

```bash
curl -X POST https://api.onehazel.com/operator-data-api/entities/player_12345/events \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "transaction",
    "data": {
      "type": "deposit",
      "amount": 50.00,
      "currency": "GBP",
      "method": "card",
      "provider": "stripe",
      "reference": "txn_abc123"
    }
  }'
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "eev_b2c3d4e5f6789012"
  }
}
```

## Step 5: Verify in the dashboard

Open [app.onehazel.com](https://app.onehazel.com) and navigate to the Analytics tab. You should see your player and transaction reflected in the KPI dashboard.

## What's next?

- [Authentication](/authentication) — API key management and security details
- [Affiliate Tag](/connectors/attribution-tag) — Capture affiliate / ad-platform attribution at landing
- [Data Ingestion](/data-ingestion/) — Full guide to entities, events, states, and batch operations
- [Workflows](/workflows) — Automate actions when events arrive
- [API Reference](/api-reference/) — Complete endpoint documentation