Quickstart

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

An API key. See how to get one.
A program to test with, created in the Hoppier dashboard.
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:

export HOPPIER_API_KEY="hk_live.…"

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.

Check your key

curl https://app.hoppier.com/api/v1/validate \
  -H "Authorization: Bearer $HOPPIER_API_KEY"

{
  "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.

Find your program

curl https://app.hoppier.com/api/v1/programs \
  -H "Authorization: Bearer $HOPPIER_API_KEY"

{
  "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.

Add a participant

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"
  }'

{
  "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.

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

Hear when the reward is ready.

Errors and retries

Handle failures safely.

API reference

Every field and error.

Get started

Concepts

Integrate

What's next

Next steps

Webhooks

Errors and retries

API reference

​Next steps

Webhooks

Errors and retries

API reference

Next steps