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": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace"
}'
import { randomUUID } from 'node:crypto';
const res = await fetch('https://app.hoppier.com/api/v1/participants', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HOPPIER_API_KEY}`,
'Content-Type': 'application/json',
// Reuse the same key if you retry this add.
'Idempotency-Key': randomUUID(),
},
body: JSON.stringify({
program: 'prg_Z8q3NnW2xK',
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
}),
});
const participant = await res.json();
import os
import uuid
import requests
res = requests.post(
"https://app.hoppier.com/api/v1/participants",
headers={
"Authorization": f"Bearer {os.environ['HOPPIER_API_KEY']}",
# Reuse the same key if you retry this add.
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"program": "prg_Z8q3NnW2xK",
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
},
timeout=30,
)
participant = res.json()
Add a participant
Adds one person to a program and returns their participant record, with a link they can use to claim their reward. The key’s owner must be an admin of the company, and the account needs an active Hoppier subscription.
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": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace"
}'
import { randomUUID } from 'node:crypto';
const res = await fetch('https://app.hoppier.com/api/v1/participants', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HOPPIER_API_KEY}`,
'Content-Type': 'application/json',
// Reuse the same key if you retry this add.
'Idempotency-Key': randomUUID(),
},
body: JSON.stringify({
program: 'prg_Z8q3NnW2xK',
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
}),
});
const participant = await res.json();
import os
import uuid
import requests
res = requests.post(
"https://app.hoppier.com/api/v1/participants",
headers={
"Authorization": f"Bearer {os.environ['HOPPIER_API_KEY']}",
# Reuse the same key if you retry this add.
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"program": "prg_Z8q3NnW2xK",
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
},
timeout=30,
)
participant = res.json()
amount on this request is in dollars (25 means $25.00). A program’s amount in every response is in cents (2500 means $25.00).- Uses one invitation from your plan, like adding someone in the dashboard.
- Already in the program? You get their existing record back, no invitation is used and no email is sent. If your account is set up to allow the same person twice in a program, they’re added again.
- No email unless you ask. Hoppier emails the person only when
sendEmailAsUsersAreAddedistrue. Otherwise, send theminviteUrlyourself. A scheduled invite email that your admins set up for the program still goes to everyone who hasn’t claimed yet, including people added here. - Retries. Send an
Idempotency-Keyso a retried request never adds anyone twice.
Authorizations
Send your key in the Authorization header: Authorization: Bearer hk_live.…. The word Bearer is case-sensitive.
Keys are issued by Hoppier during the beta and shown once. Treat them like passwords and never put one in code that runs in a browser or an app.
Headers
A UUID you generate for this add. If the request fails or times out, send it again with the same key and body: Hoppier won't add the person twice.
- Same key, same body, already finished: you get the original response again.
- Same key, different body:
422 idempotency_key_reuse. - Same key while the first request is still running:
503 in_progress; retry afterRetry-After. - The first request started more than 5 minutes ago and never finished:
409 request_outcome_unknown.
Keys are remembered for at least a day. Use a new key for each new add.
Body
Id of the program to add the person to. Starts with prg_.
"prg_Z8q3NnW2xK"
The person's email address. Hoppier stores it in lowercase.
"ada@example.com"
The person's first name.
"Ada"
The person's last name. First and last name together can be at most 24 characters.
"Lovelace"
This person's amount, in dollars (25 means $25.00), at most 500.
Only for programs where each person has their own amount, in accounts with custom program amounts turned on. Leave it out for a fixed-amount program: the program's amount applies, and sending one is refused.
25
true emails the person their invite now, using the program's "as users are added" invite email (if the program has none, nothing is sent). Leave it out to add them without an email. Send a JSON boolean: the string "false" counts as true.
false
Response
The participant: the new record, or the existing one if they were already in the program.
A person in a program.
The participant's id. Starts with pcpt_.
"pcpt_R4k1LmQ8vB"
"participant""ada@example.com"
Id of the program. Starts with prg_.
"prg_Z8q3NnW2xK"
pending: invited, hasn't claimed yet. active: claimed. inactive: no longer active in the program.
pending, active, inactive First word of the person's name. Left out when no name was given.
"Ada"
Second word of the person's name. Left out when there isn't one.
"Lovelace"
The link the person opens to claim their reward: Hoppier's sign-up page, or the sign-in page if they already have an account. Valid for 30 days. Anyone who has it can use it, so send it only to that person.
Only for accounts with public program links turned on: the program's public join link. It's the same for everyone in the program, and anyone who has it can join. Valid for 90 days.