Ambassadors
The ambassador programme: the public directory, invitations and applications, referral links and click tracking, and the ambassador portal under /me/referrals/*.
Redeem an ambassador invitation
Accepts an ambassador invitation for the signed-in account — the path for Google and Apple sign-ups, which cannot carry the token through POST /cognito/signup. The invitation is matched against the account's own registered email address; someone else's token is declined with email_mismatch.
A declined redemption is still a 200 with granted: false and a reason, so a client can always call this after sign-up even when the token was already spent. No special permission is needed.
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.
Request Body
Responses
Granted, or declined with a reason
Apply to be an ambassador
Files an application to the ambassador programme for review by FundlyHub. Works signed out; when a session is present, the application records which account filed it.
One pending application per address: a second is 409, as is an address that already holds the ambassador role.
Authentication is optional. Rate limited at 5 requests/minute per IP.
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.
Request Body
Responses
Application received
List ambassadors (public directory)
Ambassador role-holders with a public profile, ordered by the money their referral links have driven (the amounts themselves are not returned). Feeds the front-page rail.
No authentication. Rate limited at 300 requests/minute per IP.
Parameters
Query Parameters
16024Responses
The directory
List ambassadors for the endorsement picker
Ambassadors a campaign creator may ask to endorse their campaign: role-holders with a public profile, excluding the caller, with the lifetime money each has driven in cents. Authenticated because it carries those amounts.
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
Query Parameters
16024Responses
The picker list
Get an ambassador's referral analytics
All-time referral analytics for one ambassador: clicks by traffic type, conversions, attributed funds per currency, and breakdowns by campaign, UTM source and day.
Callers may read their own analytics; anyone else's answers 403.
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 ambassador's profile UUID.
"uuid"Responses
The analytics (bare object)
Get or create my referral code
Returns the caller's referral code — the profile-level one, or the one for fundraiser_id — creating it on first use. Idempotent. Share links take the form /r/{code} on the site. Every signed-in user can hold a code; the ambassador role is not required.
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.
Request Body
Responses
The code
Record a referral-link click
Called by the FundlyHub web app when a visitor opens a referral link (/r/{code}); not for third-party clients. Returns where to redirect and the visitor id to set as a cookie. Records a click classified as human, bot or unknown, and stamps the code into utm_content. When the visitor is signed in, the code is also remembered on their profile for attribution.
An unknown code still answers 200 with resolved: false and a target_path of the home page.
Authentication is optional. Rate limited per caller: 120 requests/minute, on top of the global per-IP limiter. Past the limit the answer is 429 with Retry-After.
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.
Request Body
Responses
Click processed
Get my referral summary
The ambassador portal's headline: totals, the click-to-gift funnel and a daily series for the caller's own referral links over a window (default: the 28 days ending to). Every portal route reads only the session's own rows.
Requires permission: view_own_referral_portal.
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
Query Parameters
Window start. Defaults to 28 days before to. Must be before to and not earlier than 2020-01-01.
"date-time"Window end. Defaults to now.
"date-time"Responses
The summary
List campaigns I referred to
Per-campaign clicks, visitors, driven gifts and money raised from the caller's referral links in the window.
Requires permission: view_own_referral_portal.
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
Query Parameters
Window start. Defaults to 28 days before to. Must be before to and not earlier than 2020-01-01.
"date-time"Window end. Defaults to now.
"date-time"Responses
The campaigns
Get what my referral link did for one campaign
All-time figures for the caller's own referral link on one campaign: impressions (visits not identified as a bot), clicks by traffic type, distinct human visitors, driven gifts (paid, not self-referred), distinct donors, and the value of those gifts (donation + tip) per currency in cents. The same definitions as the per-campaign rows of the ambassador analytics. Also returns the caller's referral code and link for the campaign when one exists; this read never creates one. Feeds the ambassador bar on the campaign page.
A campaign the caller may not open (draft, pending, private or deleted, and not their own) is a 404, as its page is.
Requires permission: view_own_referral_portal.
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 campaign's id.
"uuid"Responses
The caller's figures for the campaign
Get my referral traffic breakdown
Where the caller's referral clicks came from — by UTM source, referer and medium — plus traffic type, and country and device splits from Google Analytics when it is configured (ga_note says why those are null otherwise).
Requires permission: view_own_referral_portal.
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
Query Parameters
Window start. Defaults to 28 days before to. Must be before to and not earlier than 2020-01-01.
"date-time"Window end. Defaults to now.
"date-time"Responses
The breakdown
List gifts I drove
The donations attributed to the caller's referral links in the window, refunded, failed and self-referred gifts included. Each row carries exactly the fields of AmbassadorGift: no donor email, card details or receipt reference, and no donor name on an anonymous gift.
Requires permission: view_own_referral_portal.
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
Query Parameters
Window start. Defaults to 28 days before to. Must be before to and not earlier than 2020-01-01.
"date-time"Window end. Defaults to now.
"date-time"12005000Responses
One page of gifts
Get my ambassador standing
The caller's rank among ambassadors by money raised in the window, and the leaderboard (up to 200 rows; truncated when there are more). Other ambassadors with private profiles appear without name or avatar.
Requires permission: view_own_referral_portal.
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
Query Parameters
Window start. Defaults to 28 days before to. Must be before to and not earlier than 2020-01-01.
"date-time"Window end. Defaults to now.
"date-time"Responses
The standing
List my own campaigns (ambassador portal)
The campaigns the caller owns, with totals and how many clicks on their own referral links led to them (self-referrals, which do not count as driven). Takes no date range.
Requires permission: view_own_referral_portal.
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
The caller's campaigns