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

# Quickstart

> Check your Hoppier API key, find a program, add a participant and get their invite link in four requests.

This walks through the API end to end with `curl`. You'll need:

* An API key. See [how to get one](/guides/authentication.md#get-a-key).
* A program to test with, created in the [Hoppier dashboard](https://app.hoppier.com).
* An email address of your own to add.

Put the key in an environment variable so it stays out of your shell history and your code:

```bash theme={null}
export HOPPIER_API_KEY="hk_live.…"
```

> [!WARNING]
>
> There is no sandbox or test mode. Every key works against your live account: adding a participant adds a real person to a real program and uses one of your invitations. Test on a program you made for the purpose, with your own email addresses.

**1. Check your key**

```bash theme={null}
curl https://app.hoppier.com/api/v1/validate \
  -H "Authorization: Bearer $HOPPIER_API_KEY"
```

```json theme={null}
{
  "connectionId": "1a2b3c4d",
  "email": "admin@example.com",
  "company": "Acme Inc.",
  "keyType": "user",
  "message": "OK"
}
```

A `401` means the key is wrong or has been switched off.

**2. Find your program**

```bash theme={null}
curl https://app.hoppier.com/api/v1/programs \
  -H "Authorization: Bearer $HOPPIER_API_KEY"
```

```json theme={null}
{
  "programs": [
    {
      "id": "prg_Z8q3NnW2xK",
      "object": "program",
      "name": "Team lunch",
      "amount": 2500,
      "currency": "usd",
      "status": "active",
      "startDate": "1793491200000",
      "endDate": "1795996800000",
      "createdAt": "1792504992000",
      "updatedAt": "1792504992000",
      "addressId": "ad_7Ym2p0Lx3Q",
      "colorHex": "#FF6161",
      "colorHex2": "#FFFFFF",
      "logoUrl": null
    }
  ]
}
```

Copy the `id` of your test program. A program's `amount` is in **cents**: `2500` is \$25.00.

**3. Add a participant**

```bash theme={null}
curl -X POST https://app.hoppier.com/api/v1/participants \
  -H "Authorization: Bearer $HOPPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
  -d '{
    "program": "prg_Z8q3NnW2xK",
    "email": "you+test@example.com",
    "firstName": "Test",
    "lastName": "Person"
  }'
```

```json theme={null}
{
  "id": "pcpt_R4k1LmQ8vB",
  "object": "participant",
  "email": "you+test@example.com",
  "firstName": "Test",
  "lastName": "Person",
  "program": "prg_Z8q3NnW2xK",
  "status": "pending",
  "inviteUrl": "https://app.hoppier.com/signup/employee?inviteToken=eyJhbGciOiJIUzI1NiIs..."
}
```

The `Idempotency-Key` makes the request safe to retry: send it again with the same key and body, and the person is still added only once.

Without `sendEmailAsUsersAreAdded`, Hoppier doesn't email the person.

**4. Send them their link**

`inviteUrl` is the person's link to claim their reward. It's valid for 30 days. Send it to them in your own email or app, and only to them: anyone who has the link can use it.

Would you rather Hoppier sent the invite? Add `"sendEmailAsUsersAreAdded": true` to the request, and Hoppier emails the program's invite.

## Next steps

> **[Webhooks](/guides/webhooks.md)**
>
> Hear when the reward is ready.

> **[Errors and retries](/guides/errors-and-rate-limits.md)**
>
> Handle failures safely.

> **[API reference](/api-reference/overview.md)**
>
> Every field and error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.