Sponsors · Perks and the counter
Using a perk: a signed-in person's live in-store code (it changes every 30 seconds and works once, for 2 minutes), a one-time code for an online perk, receipts, and reporting a perk that wasn't honored. The counter at fundlyhub.org/counter: pairing a device to a location, checking a code and giving the perk, undoing it within 15 minutes. The business's side: perks used and answering reports. Sponsors see counts, times, places, perks and tiers, never who.
The "Use perk" screen
The perk, where it works (with each location's hours now), whether it can be used now, whether the signed-in person may use it (the tier, the 7-day hold after reaching it, once per period, "Show sponsor perks", the business's own team, a sanctioned region), their use this period and when it can be used again.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Query Parameters
Where the phone is (lat,lng), sent only when the person already lets the site know: the storefronts come nearest first, with their distance. Never cached.
"38.574,-121.481"Responses
OK
Get the key for the live code
For a person who may use the perk in store now. Returns the key their phone makes the 6-digit codes with (also offline, for 24 hours). One live key per phone, three at most: a fourth replaces the oldest. 10 new codes a minute per person, with "Get a code". Never cached.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Responses
The key
Whether the cashier has given it
The code screen polls this to turn green once the perk is given with its key. The key's owner only.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid""uuid"Responses
OK
Get a code (an online perk)
Hands the person the next one-time code from the business's list, in the same write as the use it counts as. Use it within 7 days. The team is told when it runs out, and when 10% of the list is left unless the list's low-stock alert is off. 10 new codes a minute per person.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Responses
The code
A used perk's receipt
The person's own use only; anyone else gets 404. An online use shows its code while it can still be used.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Responses
OK
My perk wasn't honored
Once per use, within 30 days. The business is told what happened (never who) and has 3 days to answer: if it confirms, or doesn't answer, the person gets the use back; if it disputes, FundlyHub decides. code_failed is for online uses.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Request Body
Responses
The receipt, with the report
Not what happened? Reply
One reply to the outcome of the person's report, once the business answered or FundlyHub decided, within 30 days. The business sees it (never who wrote it), and so do FundlyHub staff.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Request Body
Responses
The receipt, with the reply
What a pairing code would pair
"This device will check codes for Fast Cat Coffee Bar, Midtown." Does not use the code up. Codes are made in the workspace and work for 10 minutes. Ten tries per address per 10 minutes.
Request Body
Responses
OK
Pair this device
Uses the pairing code up and returns the device's session token, shown once. The device sends it on every counter request as Authorization: Counter <token>. A device signs out when the team removes it, its location closes, or after 30 days without use.
Request Body
Responses
Paired
Who is at the counter
With Authorization: Counter <token>, the paired device, its sponsor and location. Otherwise the signed-in person's sponsors and the locations they may use the counter at (owners and admins everywhere, managers and cashiers at theirs), each with whether it is open now.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Responses
OK
Check a code
A scanned QR (qr) or six typed digits (code), at this device's location, or at the location a signed-in team member picked (header X-Counter-Location). Answers with the perk and the tier, never the person. Five wrong codes in a row wait a minute; 30 checks a minute per device (or member and location), then 429 rate_limited with retryAfterSeconds.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Header Parameters
A signed-in team member's location for this shift. Not sent by a paired device.
"uuid"Request Body
Responses
The answer
Give the perk
The code checked as valid, sent back with its key and step: it is checked again, and the use is recorded by the database, which applies the perk's rule once more. Can be undone for 15 minutes. Give tapped again for a code already given here answers 200 with the same use (again: true).
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Header Parameters
"uuid"Request Body
Responses
Already given with this code (a second tap)
Undo a perk given here
Within 15 minutes, at the location it was given at. The person gets the use back. Not while a giver's report on the use waits for an answer: the report decides. The audit row names who undid it (the device, or the team member).
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Header Parameters
"uuid"Path Parameters
"uuid"Responses
Undone
Today at this counter
Today's perks at this location, in its own time zone, and who checked each one: the newest 200 listed, and the count of those that count over the whole day.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Header Parameters
"uuid"Responses
OK
Something's wrong? Report it
The cashier's note to FundlyHub about an answer the counter gave: it records the answer, the location, the time and the perk it was about, never the giver. FundlyHub staff see it in the reports queue.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Header Parameters
"uuid"Request Body
Responses
Sent
Perks used
The four totals (today, this week, this month, all time: uses that count and the people who used them: "givers thanked" from 5 up all time, "fewer than 10" under 10 otherwise) and the uses themselves, newest first, in the sponsor's home time zone. Never who. Managers see their locations. Cashiers see today at theirs, with today's total alone and no draft perks in the filter. Online uses belong to no location, so only those who see every location see them.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
The sponsor's slug, an old slug, or its id.
Query Parameters
recent is today and yesterday; yesterday is yesterday alone, in the home city. A cashier always gets today.
"recent""today""yesterday""week""month""all""custom""recent"With range=custom.
"date"With range=custom.
"date"A location id
"uuid""all""counter""online""all"The next cursor of the previous page.
50100Responses
OK
Download perks used as CSV
The same filters as the list, at most 10,000 rows. Columns time, perk, location, tier, checked_by, status.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Query Parameters
recent is today and yesterday; yesterday is yesterday alone, in the home city.
"recent""today""yesterday""week""month""all""custom""date""date""uuid""all""counter""online"Responses
CSV
Give a use back
For a perk the business didn't honor: the person gets the use back. The owner and admins. Not while a report about it waits for an answer; answer the report instead. The reason is kept with the use (Perks used shows it under "Undone") and in the audit row.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Request Body
Responses
Voided
Reports about perks used
Newest first, scoped like perks used, with how many came in the last 90 days. What happened, never who said so. Owners, admins and staff see every report, and managers see their locations'. Cashiers get 403: they see today's uses alone.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Responses
OK
Answer a report
Within 3 days. confirm gives the person the use back at once; dispute, with what happened, goes to FundlyHub, who decide. A report not answered in 3 days is decided for the person. The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Request Body
Responses
Answered
Online code lists
Every online perk with its list of one-time codes, how many are left, and the uploads. The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Responses
OK
Upload one-time codes
A CSV's text, one code per line in the first column (a code header is skipped), at most 50,000. A code already on the perk's list or in the file, in any case, is refused, with its line; codes are stored encrypted. An upload that takes the perk from no codes left to some tells the givers watching it ("Tell me when it's back"). The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Request Body
Responses
Uploaded
Remove an upload's unused codes
Codes already handed out stay, with their upload, as the record of their uses. The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Responses
Removed
A code list's low-stock alert
Whether the owner and admins are emailed when 10% of this list is left. Running out is always told. The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"uuid"Request Body
Responses
Saved
The connections I asked about
Which connections that come later (an online shop, point of sale, loyalty, the developer API) the signed-in person asked to hear about for this business. The owner and admins.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Responses
OK
Tell me when it's ready
Kept per business, connection and person. Asking twice is the same ask.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Request Body
Responses
Asked