Skip to content

Sponsors​

Local businesses that give perks to people who hold FundlyHub achievements. Sponsors never receive donations. The directory (by city, category, name or what you can use), a sponsor's page and its perks, locations, impact and updates, following a sponsor, a sticker's page, reporting wrong information, and a signed-in person's My perks. A sponsor's {key} takes its current slug, an old one or its id. A sponsor that is not live yet is visible only to its team and to staff; anyone else gets 404. Every operation answers 403 while sponsors are switched off.


The menus' sponsor entries​

GET
/me/sponsor-menu

What the header, the account menu and the footer show about sponsors. 403 means sponsors are switched off and the menus show no sponsor entries. For a signed-in person: the businesses they are on the team of (each linked to its workspace) and whether they use the counter. Answers a visitor who is not signed in too, with both empty, so the Community menu and the footer know sponsors are on. Never cached (Cache-Control: private, no-store).

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

Playground​

Server

Samples​


What the web badge shows​

GET
/sponsors/{key}/badge

The answer the Proud Sponsor web badge is drawn from. The badge itself is the image at https://fundlyhub.org/badge/sponsor/{slug}.svg (?theme=dark for the white version on a dark page, ?size=small for 160 by 38, ?size=round for the 48 by 48 round mark), which always shows the sponsor's live status. {key} takes the current slug, an old one or the id, so a badge keeps working after a rename. Cacheable for 5 minutes. 403 while sponsors are switched off.

Parameters​

Path Parameters

key*
Type
string
Required
Example"fast-cat-coffee-bar"

Responses​

OK

application/json
JSON
{
"badge": "proud_sponsor",
"slug": "fast-cat-coffee-bar",
"name": "Fast Cat Coffee Bar"
}

Playground​

Server
Variables
Key
Value

Samples​


List sponsors​

GET
/sponsors

The sponsor directory: live or paused sponsors with a perk that is live, or ended less than 30 days ago. A city lists the sponsors with an open location whose address is in it, the same rule its "14 sponsors" counts by. Nearest first from near (a point the person chose to share; it only sorts), else from a signed-in viewer's own place, else by name. Each card leads with the perk the signed-in viewer can best use there, its state for them, and how many they can use; a guest sees neither. viewer.usable is the viewer's count over the whole city (the other filters aside). Without a city a signed-in viewer sees their own (cityDefault); city=all is every city.

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​

Query Parameters

city

A city page's slug, or all. Absent: a signed-in viewer's own city, else every city.

Type
string
category

Category ids, comma separated (coffee_cafe,bakery).

Type
string
q

Part of the name, a name it trades under, one of its places' names ("Midtown") or one of its perks.

Type
string
Max Length
80
near

lat,lng to sort from. Without it, a signed-in viewer's own place.

Type
string
Example"38.5762,-121.4805"
can_use

Signed in only - just the sponsors with a perk the viewer can use.

Type
string
Valid values
"true""1"
open_now

Just the sponsors with a storefront open now.

Type
string
Valid values
"true""1"
nearby

Just the sponsors with a storefront within 5 miles of the point (ignored without one).

Type
string
Valid values
"true""1"
new

Just the sponsors approved in the last 30 days.

Type
string
Valid values
"true""1"
online

Just the sponsors that sell online (online only

Type
string
Valid values
"true""1"
offers_help

Just the ones with help in Find help (#2423). Ignored while Resources are switched off.

Type
string
Valid values
"true""1"
limit
Type
integer
Default
24
Maximum
48
offset
Type
integer
Default
0

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


List sponsor categories​

GET
/sponsors/categories

The business categories in display order, each with its policy (allowed, limited - bars, breweries and wineries can't give perks on alcohol, pharmacies not on prescriptions -, or not_allowed) and the number of listed sponsors in it (in city, when given). Names are the site's translations of the id.

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​

Query Parameters

city

A city page's slug.

Type
string

Responses​

OK

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

Playground​

Server
Variables
Key
Value

Samples​


Perks for one achievement card​

GET
/sponsors/perks

The perks of listed sponsors for one achievement, split at a card's tier: unlocks are the perks for that tier and below, higher counts the perks of each tier above with two examples, never how far the holder is from it. The card's code and QR are public and never unlock a perk; for a signed-in holder each perk carries their own eligibility.

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​

Query Parameters

achievement*

The achievement's slug or id.

Type
string
Required
tier
Type
string
Valid values
"base""bronze""silver""gold"
Default
"base"
city
Type
string
near
Type
string
limit
Type
integer
Default
4
Maximum
24

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


Get a sponsor's page​

GET
/sponsors/{key}

A sponsor's page for the person looking: the business, its numbers (from the same views the workspace and the admin portal read; givers thanked from 5 up), its perks with the viewer's eligibility, its open locations, the latest updates, the team members shown on the page (never cashiers), what FundlyHub checked (only checks that passed), and the viewer block (following, their role on the team, whether they may open the workspace). The team and staff also get teamWeek and each perk's counted uses. A live, paused, suspended or closed sponsor is public; any other is visible to its team and to staff only, and answers 404 to anyone else. An old slug answers with the current one in slug and renamed: true. A closed sponsor's page is a record: no perks.

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

Type
string
Required

Query Parameters

near

lat,lng for each location's distance (the browser's position, when the person allowed it). Without it, a signed-in viewer's own place on their profile is used; never a guess from the IP address.

Type
string

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


List a sponsor's perks​

GET
/sponsors/{key}/perks

The perks the public sees: live, paused and scheduled, and an ended one for 30 days; never one FundlyHub stopped or one not approved yet. Each with its availability for everyone and the viewer's eligibility.

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

Type
string
Required

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


Get one of a sponsor's perks​

GET
/sponsors/{key}/perks/{perkId}

One perk with where it works in store (each place's state today and any closure ahead), when it went live, and the viewer's eligibility. 404 for a perk of another sponsor, one the public doesn't see, or any perk of a closed sponsor.

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

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

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


List a sponsor's locations​

GET
/sponsors/{key}/locations

The open locations, home first. A storefront shows its street address and map point; a business that comes to customers shows the ZIP codes it serves and never its address (often a home); an online-only business shows its city. Each with its weekly hours, whether it is open now, closed now or temporarily closed (in its city's time zone), a closure within 30 days, whether its address is confirmed, and which perks work there. A location closed for good is not listed.

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

Type
string
Required

Query Parameters

near

lat,lng for each location's distance. Without it, a signed-in viewer's own place on their profile is used; never a guess from the IP address.

Type
string

Responses​

OK

application/json
JSON
{
"locations": [
],
"perksByLocation": {
"additionalProperties": [
]
},
"team": true
}

Playground​

Server
Variables
Key
Value

Samples​


Get a sponsor's impact​

GET
/sponsors/{key}/impact

Counts, never dollars: perks used (in-store uses confirmed at the counter plus online codes handed out, minus any undone or voided), givers thanked (different people, from 5 up), followers and the new ones this week, sponsor since, and the uses by perk, by place (online apart) and by month in the home city's time zone, each adding up to the total. Never the gifts its customers made, which count as their own giving and their city's.

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

Type
string
Required

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


List a sponsor's updates​

GET
/sponsors/{key}/updates

Updates on the page, newest first, with who posted each (a team member's name and role, FundlyHub, or posted automatically when a perk went live).

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​

Path Parameters

key*

The sponsor's slug, a slug it used to have, or its id.

Type
string
Required

Query Parameters

limit
Type
integer
Default
10
Maximum
50
offset
Type
integer
Default
0

Responses​

OK

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

Playground​

Server
Variables
Key
Value

Samples​


Follow a sponsor​

POST
/sponsors/{key}/follow

Follows the sponsor and answers its follower count; following again changes nothing. A sponsor sees how many follow it, never who. A closed sponsor takes no new followers (409 sponsor_closed).

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, a slug it used to have, or its id.

Type
string
Required

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Unfollow a sponsor​

DELETE
/sponsors/{key}/follow

Stops following; always allowed, and a no-op when not following.

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, a slug it used to have, or its id.

Type
string
Required

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Report wrong information​

POST
/sponsors/{key}/reports

Tells FundlyHub something on the page, or at one of its locations, is wrong. Staff handle it; the business never learns who reported. A second report of the same thing by the same person within a day answers 200 with the first one (duplicate: true). Needs a verified email. A perk that wasn't honored is reported from the use's receipt instead.

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, a slug it used to have, or its id.

Type
string
Required

Request Body​

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

Responses​

The same report, made within the last day.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Read a Proud Sponsor sticker​

GET
/sticker/{code}

What fundlyhub.org/sticker/{code} says. Giving first: the Fundlies in the sticker's city (a gift goes to the Fundly, never to the business). Then status: real (the business, the location and the perks there, for this viewer), replaced (a lost or damaged sticker was reordered and its code stopped working), location_closed, ended (the business is no longer a sponsor), or unknown (no sticker has this code; it may be a copy). Someone on the team at the location also gets team, with whether they can confirm the address with this sticker.

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​

Path Parameters

code*

The code printed in the sticker's QR (any case).

Type
string
Required
Example"K7Q2MX"

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


Confirm a location's address with its sticker​

POST
/sticker/{code}/confirm

Someone on the team who works at the sticker's location confirms its address: the sticker was mailed there. Each sticker confirms once, and an address that is already confirmed answers 409.

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

code*

The code printed in the sticker's QR (any case).

Type
string
Required
Example"K7Q2MX"

Responses​

Confirmed.

application/json
JSON
{
"confirmed": true,
"confirmedAt": "string",
"locationId": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Report a sticker​

POST
/sticker/{code}/report

A sticker that looks fake, or that is still up after it was replaced or its sponsor left. Kept with the code as scanned and, for a real sticker, its sponsor and location. Same one-a-day rule as other reports. Needs a verified email.

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

code*

The code printed in the sticker's QR (any case).

Type
string
Required
Example"K7Q2MX"

Request Body​

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

Responses​

The same report, made within the last day.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


My perks​

GET
/me/perks

The signed-in person's perks at listed sponsors. ready: perks they qualify for (they hold the tier and its 7 days have passed), including ones used as often as they allow; other: perks for a tier they don't hold yet, or hold but still wait out; saved; used: their counted uses, newest first. counts covers every tab, unlocking groups the tiers whose wait is running with the day it ends. Perks of a sponsor they work for are never ready or other. With "Show sponsor perks" off (show_sponsor_perks in the user's preferences) ready and other are empty and perksOff is true.

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​

Query Parameters

tab
Type
string
Valid values
"ready""other""saved""used"
Default
"ready"
city

A city's slug, or all. Absent: the person's own city.

Type
string
category
Type
string
online

Just the perks used online.

Type
string
Valid values
"true""1"
near

lat,lng to sort from. Without it, the person's own place.

Type
string
limit
Type
integer
Default
20
Maximum
50
offset
Type
integer
Default
0

Responses​

OK

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Save a perk​

PUT
/me/perks/{perkId}/save

Adds a perk the public can see to My perks, Saved. Saving it again changes nothing.

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​

OK

application/json
JSON
{
"saved": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Unsave a perk​

DELETE
/me/perks/{perkId}/save

Removes a perk from Saved; always allowed.

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​

OK

application/json
JSON
{
"saved": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Tell me when a perk's codes are back​

PUT
/me/perks/{perkId}/watch

"Tell me when it's back" under an online perk that is out of codes. When an upload takes the perk from no codes to some, the person is told once (bell and email) and the watch ends. Watching it again changes nothing.

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​

OK

application/json
JSON
{
"watching": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Stop waiting for a perk's codes​

DELETE
/me/perks/{perkId}/watch

Ends the watch; always allowed.

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​

OK

application/json
JSON
{
"watching": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Powered by VitePress OpenAPI

Built with VitePress