Skip to content

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​

GET
/perks/{perkId}/use

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

perkId*
Type
string
Required
Format
"uuid"

Query Parameters

near

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.

Type
string
Example"38.574,-121.481"

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Get the key for the live code​

POST
/perks/{perkId}/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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

perkId*
Type
string
Required
Format
"uuid"

Responses​

The key

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Whether the cashier has given it​

GET
/perks/{perkId}/code/{keyId}

The code screen polls this to turn green once the perk is given with its key. The key's owner only.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

perkId*
Type
string
Required
Format
"uuid"
keyId*
Type
string
Required
Format
"uuid"

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Get a code (an online perk)​

POST
/perks/{perkId}/online-code

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

perkId*
Type
string
Required
Format
"uuid"

Responses​

The code

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


A used perk's receipt​

GET
/perk-uses/{useId}

The person's own use only; anyone else gets 404. An online use shows its code while it can still be used.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

useId*
Type
string
Required
Format
"uuid"

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


My perk wasn't honored​

POST
/perk-uses/{useId}/report

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

useId*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"kind": "string",
"note": "string"
}

Responses​

The receipt, with the report

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Not what happened? Reply​

POST
/perk-uses/{useId}/report/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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

useId*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"reply": "string"
}

Responses​

The receipt, with the reply

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


What a pairing code would pair​

POST
/counter/pair/preview

"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​

application/json
JSON
{
"code": "048213"
}

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Body

Samples​


Pair this device​

POST
/counter/pair

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​

application/json
JSON
{
"code": "string"
}

Responses​

Paired

application/json
JSON
{
"data": {
"device": {
"id": "string",
"name": "string"
},
"sponsor": {
"id": "string",
"slug": "string",
"name": "string",
"logoUrl": "string"
},
"location": {
"id": "string",
"label": "string",
"city": "string"
},
"token": "string"
}
}

Playground​

Server
Body

Samples​


Who is at the counter​

GET
/counter/session

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server

Samples​


Check a code​

POST
/counter/check

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Counter-Location

A signed-in team member's location for this shift. Not sent by a paired device.

Type
string
Format
"uuid"

Request Body​

application/json
JSON
{
"qr": "FHP1:5b0e8d4c-2f1a-4c39-9d77-0a1b2c3d4e5f:59012345:048213",
"code": "string"
}

Responses​

The answer

application/json
JSON
{
"data": "string"
}

Playground​

Server
Headers
Body

Samples​


Give the perk​

POST
/counter/give

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Counter-Location
Type
string
Format
"uuid"

Request Body​

application/json
JSON
{
"keyId": "string",
"step": 0,
"code": "string"
}

Responses​

Already given with this code (a second tap)

application/json
JSON
{
"data": "string"
}

Playground​

Server
Headers
Body

Samples​


Undo a perk given here​

POST
/counter/uses/{useId}/undo

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Counter-Location
Type
string
Format
"uuid"

Path Parameters

useId*
Type
string
Required
Format
"uuid"

Responses​

Undone

application/json
JSON
{
"data": {
"useId": "string",
"undoneAt": "string"
}
}

Playground​

Server
Headers
Variables
Key
Value

Samples​


Today at this counter​

GET
/counter/today

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Counter-Location
Type
string
Format
"uuid"

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Headers

Samples​


Something's wrong? Report it​

POST
/counter/problem

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Counter-Location
Type
string
Format
"uuid"

Request Body​

application/json
JSON
{
"answer": "string",
"note": "string",
"perkId": "string"
}

Responses​

Sent

application/json
JSON
{
"data": {
"reportId": "string"
}
}

Playground​

Server
Headers
Body

Samples​


Perks used​

GET
/sponsors/{key}/manage/uses

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*

The sponsor's slug, an old slug, or its id.

Type
string
Required

Query Parameters

range

recent is today and yesterday; yesterday is yesterday alone, in the home city. A cashier always gets today.

Type
string
Valid values
"recent""today""yesterday""week""month""all""custom"
Default
"recent"
from

With range=custom.

Type
string
Format
"date"
to

With range=custom.

Type
string
Format
"date"
location

A location id

Type
string
perk
Type
string
Format
"uuid"
channel
Type
string
Valid values
"all""counter""online"
Default
"all"
before

The next cursor of the previous page.

Type
string
limit
Type
integer
Default
50
Maximum
100

Responses​

OK

application/json
JSON
{
"data": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Download perks used as CSV​

GET
/sponsors/{key}/manage/uses/export

The same filters as the list, at most 10,000 rows. Columns time, perk, location, tier, checked_by, status.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Query Parameters

range

recent is today and yesterday; yesterday is yesterday alone, in the home city.

Type
string
Valid values
"recent""today""yesterday""week""month""all""custom"
from
Type
string
Format
"date"
to
Type
string
Format
"date"
location
Type
string
perk
Type
string
Format
"uuid"
channel
Type
string
Valid values
"all""counter""online"

Responses​

CSV

text/csv
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Give a use back​

POST
/sponsors/{key}/manage/uses/{useId}/void

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required
useId*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"reason": "string"
}

Responses​

Voided

application/json
JSON
{
"data": {
"useId": "string",
"voidedAt": "string"
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Reports about perks used​

GET
/sponsors/{key}/manage/reports

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Responses​

OK

application/json
JSON
{
"data": {
"reports": [
],
"last90Days": 0
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Answer a report​

POST
/sponsors/{key}/manage/reports/{reportId}/answer

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required
reportId*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"decision": "string",
"answer": "string"
}

Responses​

Answered

application/json
JSON
{
"data": {
"reportId": "string",
"status": "string"
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Online code lists​

GET
/sponsors/{key}/manage/online-codes

Every online perk with its list of one-time codes, how many are left, and the uploads. The owner and admins.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Responses​

OK

application/json
JSON
{
"data": {
"perks": [
]
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Upload one-time codes​

POST
/sponsors/{key}/manage/online-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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Request Body​

application/json
JSON
{
"perkId": "string",
"csv": "string",
"filename": "string"
}

Responses​

Uploaded

application/json
JSON
{
"data": {
"batchId": "string",
"added": 0,
"duplicates": 0,
"duplicateLines": [
0
],
"invalid": [
"string"
]
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Remove an upload's unused codes​

DELETE
/sponsors/{key}/manage/online-codes/batches/{batchId}

Codes already handed out stay, with their upload, as the record of their uses. The owner and admins.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required
batchId*
Type
string
Required
Format
"uuid"

Responses​

Removed

application/json
JSON
{
"data": {
"removed": 0,
"batchKept": true
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


A code list's low-stock alert​

PUT
/sponsors/{key}/manage/online-codes/{perkId}/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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required
perkId*
Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"lowStock": true
}

Responses​

Saved

application/json
JSON
{
"data": {
"perkId": "string",
"lowStockAlert": true
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


The connections I asked about​

GET
/sponsors/{key}/manage/connect

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Responses​

OK

application/json
JSON
{
"data": {
"asked": [
"string"
]
}
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Tell me when it's ready​

POST
/sponsors/{key}/manage/connect

Kept per business, connection and person. Asking twice is the same ask.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

key*
Type
string
Required

Request Body​

application/json
JSON
{
"kind": "string"
}

Responses​

Asked

application/json
JSON
{
"data": {
"asked": [
"string"
]
}
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Powered by VitePress OpenAPI

Built with VitePress