Communities API
A community is a group of people on FundlyHub (a neighbourhood, a church, a diaspora, a school, a workplace) who show up for each other's Fundlies. When a member shares a Fundly to a community, the other members hear about it, each on their own terms. This page covers the directory and the community page, roles, joining and invites, posts, sharing Fundlies, alert settings, and community money: paid membership and the community fund.
| Reference section | Operations | About |
|---|---|---|
| Communities | 82 | Communities, such as a church, a school, a workplace or a city: the directory and featured lists, a community's page and its tabs, joining (one tap, by request, or a paid membership), people, invites and invite links, roles (owner, leaders, volunteers, members), posts, sharing Fundlies to a community (with leader approval where it is required), the community fund and its Stripe account, and each person's community settings. A community is named by its slug or its uuid (`{key}`, or `{id}` under `/communities/`). Reads answer `404` for a deleted community, a draft (except to its owner) and a hidden or suspended community (except to its members); a suspended community is read-only. Moving the fund's money and opening its Stripe links need a real signed-in session: an API key or an impersonating admin cannot. |
{key} and {id} are the same thing
Every {key} (and {id} on the money endpoints) takes the community's slug or uuid; a slug matches case-insensitively. A deleted community is a 404 everywhere.
The community card
CommunityCard is the shape of every list: the directory, the home page, a profile, a city page, /me/communities, the share step.
| Field | Notes |
|---|---|
id, slug, name, href | href is the site path, /communities/<slug>. |
kind | city, church, diaspora, families, school, workplace or other (the default). |
city_text, place_id, place_slug | The city as typed, the city it was placed in, and that city's slug when its page exists. |
photo_url, avatar_url | Images uploaded to FundlyHub, or null. |
visibility | public, or private: the feed and member list are for members, and joining needs approval. |
listed | false keeps it out of the directory and city pages; it stays reachable by link. |
membership, price_cents, yearly_price_cents, currency | free or paid; monthly and yearly dues in integer cents; usd. |
join_approval | none, or leaders: every join is a request. |
status | active; draft (seen by its owner only); hidden or suspended, set by FundlyHub and seen by members only. A suspended community is read-only. |
featured | Picked by FundlyHub. |
member_count, fundly_count | Active members, and the verified Fundlies posted here. |
impact_cents | Community impact, all time: money into the community fund, plus what Fundlies shared here raised, plus what members gave and drove to other Fundlies, each gift counted once. The same figure the page, the directory and the leaderboard show. |
viewer | The caller's { role, status, join_action }; see Joining. |
Church communities
kind: "church" marks a church community, and GET /communities?category=church lists them. Otherwise a church community is an ordinary community: the same roles, joining, sharing, alert and money rules apply, and the API applies no other rule by kind. Churches can also exist as verified non-profits: GET /nonprofits?kind=church lists the verified non-profits FundlyHub classifies as churches. Those are organizations, not communities; a city page lists them under nonprofits with is_church: true.
Public reads
| Endpoint | Purpose |
|---|---|
GET /communities | The directory. |
GET /communities/top | Top communities this calendar month (UTC): metric impact (default), new_members or funded; limit default 5, max 20. Only communities scoring above zero. |
GET /home/featured-communities | Featured first, then the biggest. limit default 4, max 12. |
GET /communities/{key} | The community page (below). |
GET /communities/{key}/about | The About tab: about, links, city_page, languages, guidelines, kind, the plan, stats and team. |
GET /communities/{key}/fundlies | The Fundlies posted here. |
GET /communities/{key}/feed | The feed. Members only in a private community. |
GET /communities/{key}/members | The members. Members only in a private community. |
GET /users/{id}/communities | A person's communities, for their profile (uuid or handle). |
GET /communities/invites/{token} | What an invite link or an emailed invite is for. |
GET /communities/form-rules | Every limit and choice the create and settings forms hold to, read from the constants the server validates with. |
Credentials are optional; send them to get the caller's viewer state on every card. No community endpoint takes ?lang=: names, about, guidelines and posts come back as written, and Fundly rows carry the campaign's original title and summary.
The directory
GET /api/v1/communities
Active, listed communities, public and private alike.
| Query | Notes |
|---|---|
q | Case-insensitive substring of the name, city_text or about. Ignored under 2 characters. |
category | all (default), paid, or a kind. Anything else is a 400 with allowed. |
sort | featured (default: featured first, then the most members, then the newest), members, new, or impact (all-time Community impact; raised is accepted for it). Anything else is a 400. |
limit, offset | limit default 24, max 48; offset default 0. |
curl "https://api.fundlyhub.org/api/v1/communities?category=church&limit=1"{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000", "slug": "st-marys-sacramento",
"name": "St. Mary's Sacramento", "href": "/communities/st-marys-sacramento", "kind": "church",
"city_text": "Sacramento, CA", "place_id": "9b1d2c3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e", "place_slug": "sacramento-ca",
"photo_url": null, "avatar_url": null, "visibility": "public", "listed": true,
"membership": "free", "price_cents": null, "yearly_price_cents": null, "currency": "usd",
"join_approval": "none", "status": "active", "featured": false,
"member_count": 48, "fundly_count": 3, "impact_cents": 412500, "created_at": "2026-09-14T17:02:11.000Z",
"viewer": { "role": null, "status": null, "join_action": "join" }
}
],
"total": 7,
"pagination": { "total": 7, "limit": 1, "offset": 0, "has_more": true },
"counts": { "all": 41, "paid": 3, "city": 9, "church": 7, "diaspora": 6, "families": 5, "school": 4, "workplace": 2, "other": 8 }
}counts covers every category for the same q, whatever category you sent.
The community page
GET /api/v1/communities/{key} answers { data: CommunityDetail }, the card plus everything the page shows. It is a 404 for a draft (except to its owner) and for a hidden or suspended community (except to its members). A private community answers 200: its page, About tab and Fundlies are public, while its feed and member list answer 403 MEMBERS_ONLY to anyone but members.
about,languages,guidelines, andlinks: up to 8, in order, never one flagged by Safe Browsing or removed by FundlyHub; a members-only link (such as an invite into a group chat) only for active members.city_page: the city block (slug,label,fundlies,donors,has_page, …), ornull. Link to/cities/<slug>only whenhas_page.- The settings:
share_policy,add_policy,default_alert,show_leaders,perks,leaders_join_free. stats: member and Fundly counts,impact_centswith its four parts inimpact(fund_cents,raised_cents,given_cents,driven_cents, which add up to it),gift_count,new_members_month,team_count.team: the owner, leaders and volunteers; empty whenshow_leadersis off and the caller is not the owner or a leader.pinned_post, ornull: alsonullfor anyone the feed refuses (a non-member of a private community), since a pinned post is a feed post. Itsauthorisnullwhen roles are hidden from the caller.viewer: the card's three fields, plus the caller's alert settings, paid state (is_paid_member,renews_at,paid_price_cents) andcan, the permissions the caller holds here.invite: the caller's own share link (active members);setup, the owner's checklist;suspended_reasonfor the owner and leaders.
Fundlies, feed and members
| Tab | Query | Returns |
|---|---|---|
| Fundlies | status: active (default: live, not fully funded), funded, or ended (neither). sort: newest (default, by when it was posted here), most_raised, ending. q (2+ characters): title, location, organizer name. limit default 24, max 48. | Campaign listing rows plus organizer_name, raised_cents, goal_cents, percent, remaining_cents, is_primary, posted_at. total counts the chosen status; counts gives all three for the same q. |
| Feed | before: the previous page's next_before (null once a page comes back short). limit default 20, max 50. | Newest first, by kind: post, created, fundly_posted, milestone_reached, goal_reached, update_posted (on a Fundly posted here), members_joined (grouped by week), and fund_allocated, fund_withdrawn, fund_dues for callers who can see the fund. Never the pinned post. With show_leaders off, a caller below leader sees posts attributed to the community (actor: null, attributed_to_community: true). |
| Members | role: all, team, leaders, volunteers, members. filter=new_month. q (2+ characters): names and handles of public profiles. limit default 48, max 100. | The team first, then members, newest first; with show_leaders off and a caller below leader, one list with role: null. A private profile is listed as "A member", with no photo or link. joined_via, added_by_name and impact_cents only for the owner, leaders and volunteers. |
Creating and editing
| Endpoint | Auth | Notes |
|---|---|---|
POST /communities | Signed in, verified email | The caller becomes the owner; one person may own up to 10 (409 LIMIT_REACHED). Only name (2–80 characters) is required; the slug is made from it unless you send one (a taken one is 409 SLUG_TAKEN with a suggestion). about takes up to 280 characters; images must be uploaded to FundlyHub first; the other limits are in GET /communities/form-rules. draft: true keeps it to the owner until they publish. co_leaders ([{ user_id, role: "leader" | "volunteer" }]) are invited, not added. 201 with the page object. |
GET /communities/slug-available?slug= | Signed in | { slug, available, reason: "taken" | "reserved" | "invalid" | null, suggestion }. |
PATCH /communities/{key} | Owner, leaders | The create fields except co_leaders, links and draft. The plan fields (membership, prices, perks, leaders_join_free) are the owner's. publish: true turns the owner's draft live. |
GET · PUT /communities/{key}/links | Owner, leaders | The links with their Safe Browsing status and 30-day clicks; PUT { links: [...] } replaces the ordered list. A refused row is a 400 with details: { index, reason }. |
DELETE /communities/{key} | Owner | A soft delete. 409 HAS_MONEY, with blockers, while paid memberships are live, the fund's balance is not zero or a dispute is open; a suspended community cannot be deleted. |
POST /communities/{key}/report | Signed in, verified email | { reason: "spam" | "scam" | "harassment" | "inappropriate" | "other", details?, link_id? }. One report per person and community; a repeat updates it. |
POST /communities/{key}/links/{linkId}/click | Public | A click beacon; always 204, stores no user id. |
Roles and permissions
Community roles live on the membership; they are not the platform's RBAC roles.
| Role | Adds to the role below |
|---|---|
member | Shares their own Fundlies, has their own invite link, and may add people when add_policy is members. |
volunteer | Adds and invites people, approves join requests, posts. |
leader | Edits settings and links, changes roles below leader, removes volunteers and members, pins posts, approves shared Fundlies. |
owner | Makes and unmakes leaders, transfers ownership, deletes the community, and runs its money. One per community. |
A community has at most 10 leaders, the owner included (409 LEADER_LIMIT). viewer.can on the page is this matrix for the caller. A suspended community is read-only for everyone, and a draft is its owner's alone.
| Endpoint | Who |
|---|---|
PATCH /communities/{key}/members/{userId} | { "role": "leader" | "volunteer" | "member" }. The owner, or a leader for roles below leader. |
DELETE /communities/{key}/members/{userId} | The owner, or a leader for volunteers and members. Never the owner. |
POST /communities/{key}/transfer | The owner: { "user_id", "leave"?: true }. The new owner must be an active leader (409 NOT_A_LEADER); the old owner becomes a leader, or leaves. |
GET /communities/{key}/alert-counts | Owner, leaders, volunteers: how many members get instant, digest, off and muted. Counts only. |
Joining
viewer.join_action tells a client what its Join button does:
join_action | Meaning |
|---|---|
join | POST /communities/{key}/join joins at once. |
request | Private, or join_approval: leaders: the same call files a request. |
pay | Paid membership: use POST /communities/{id}/join/paid. |
accept_invite | The caller holds a pending invite; joining accepts it, with its role. |
joined, requested | Already a member; request pending. |
none | Not possible now: the community is not active, or the caller was removed. |
POST /communities/{key}/join takes an optional invite (a share-link code or an invite token) and via (qr, link or directory), and answers { data: { status: "active" | "requested", viewer } }. A share link made by a current owner or leader with approval switched off joins directly. Refusals: 402 PAYMENT_REQUIRED for a paid community (checkout names the paid join), 403 REMOVED for a removed person, who comes back only through an invite addressed to them, and 409 COMMUNITY_NOT_ACTIVE.
| Endpoint | Notes |
|---|---|
POST /communities/{key}/leave | Leaves, or withdraws a request: { data: { left: true, access_until: null } }. The owner gets 409 OWNER_MUST_TRANSFER; a member whose paid membership still renews gets 409 PAID_MEMBERSHIP_ACTIVE with a cancel_path. |
GET /communities/{key}/requests · POST …/requests/{userId}/approve · …/deny | Owner, leaders and volunteers. …/decline is an alias of deny. A denied request is deleted, so the person may ask again. |
Invites
- Share links. Each member has their own link,
https://fundlyhub.org/communities/<slug>?invite=<code>with an 8-character code, made on first use, and joins through it credit them.GET /communities/{key}/invite-linkreturns{ token, url, uses, requires_approval, expires_at };POST …/invite-link/rotatereplaces the code;PATCH …/invite-link(owner and leaders) setsrequires_approvalandexpires_in_days(1, 7, 30, 90 ornull). Below leader, a link follows the community's approval rule. - Personal invites.
POST /communities/{key}/invitestakesemails,user_idsand arole(memberby default) and sends an in-app notice and an email. Each invite is single use and lasts 14 days. Only the owner invites leaders, and only the owner and leaders invite volunteers; whoever may add people may invite, and any member may invite with thememberrole.GET …/inviteslists the pending ones (owner, leaders, volunteers);POST …/invites/{inviteId}/resendsends a fresh link good for 14 more days, once a day (429 RESEND_TOO_SOON);DELETE …/invites/{inviteId}cancels one. - Accepting.
GET /communities/invites/{token}previews either kind, publicly.POST …/acceptjoins: a share link behaves exactly likejoinwith that code, a personal invite joins with its role.POST …/declinedeclines a personal invite. An invite addressed to an account works only for that account (403 NOT_YOUR_INVITE); an expired or used one is410 INVITE_INVALID; amemberinvite into a paid community is402.
Adding people
POST /communities/{key}/members{ "user_ids": [...] } (owner, leaders, volunteers, and members when add_policy is members) adds or invites each person by their "Who can add you" setting (add_policy in community settings): anyone is added; follows_and_shared (the default) is added when they follow the adder or already share a community with them, else invited; nobody is always invited. A paid community only invites. Adding someone who asked to join approves the request. The answer is { data: { added, invited, skipped, skipped_reasons }, remaining_today }, and an added person gets one notification and email with a Leave link. GET /communities/{key}/people is the picker: q (2+ characters) matches public names and handles, or an exact email address; with no q, people the caller knows. Each row's state (addable, invite_only, no_adds, member, invited, requested, removed) says what Add will do. Adds and personal invites share one budget: 50 per person in any 24 hours, across all communities, and at most 50 people per request.
Posts
| Endpoint | Who |
|---|---|
POST /communities/{key}/posts | Owner, leaders, volunteers. { "body": "…", "pinned"?: true }, 1–2,000 characters. 201. One post is pinned at a time, so pinning unpins the previous one; the pinned post shows as pinned_post on the page, not in the feed. |
PATCH /communities/{key}/posts/{postId} | The author edits body; the owner and leaders edit any post and set pinned. |
DELETE /communities/{key}/posts/{postId} | The author, or the owner and leaders. |
Sharing a Fundly
A Fundly's organizer shares it to up to 3 of their communities, one of them primary, with PUT /fundraisers/{id}/communities:
{ "communities": [ { "community_id": "st-marys-sacramento", "primary": true } ] }- Organizer only.
community_idtakes an id or a slug. At most 3 (400 TOO_MANY), exactly oneprimary(400 PRIMARY_REQUIRED), none twice; a community left out loses the share, and[]removes them all. A new share needs the organizer to be an active member (403 NOT_A_MEMBER). - A share clears at once when the community's
share_policyisautoor the organizer is its owner or a leader. Otherwise it waits for the owner or a leader:GET /communities/{key}/pending-fundlies, thenPOST …/fundlies/{fundraiserId}/approveor…/reject. - A cleared share is posted, and the members alerted, once the Fundly has passed verification (status
active, public, not deleted). Until thenGET /fundraisers/{id}/communitiesshows each share'sawaiting:leader_approvalorverification. - For the share step,
GET /me/communities/shareable?fundraiser_id=lists the caller's active communities with this Fundly's share state, andGET /communities/reach?ids=(up to 3 of the caller's communities) counts who would hear about it, never who. - A Fundly's detail read,
GET /fundraisers/{id}, carriescommunities: up to 3 active, listed communities it is posted in, primary first.
Alerts and settings
A member sets how they hear about new Fundlies in each community with GET /communities/{key}/me and PATCH /communities/{key}/me: alert_level (instant, digest or off), channels (["email", "web"], or a partial object such as { "push": false }), mute_days (1, 7, 30 or 90) or muted_until (null unmutes), and pinned_home. A new member starts at the community's default_alert, every channel on.
- A posted Fundly alerts the members of every community it is posted in, except its organizer, once per person per Fundly; across several memberships the most immediate level wins.
- Quiet hours, on by default: an instant alert raised between 22:00 and 07:00 in the person's timezone waits until 07:00. At most 3 instant alerts a local day; the rest go to the digest, which goes out on Mondays at 9am local time.
pushis stored but not delivered: there is no push pipeline yet.- Community emails follow the account's email preferences and carry one-click unsubscribe: mail providers
POSTto/unsubscribe/one-click?token=, which turns that category of email off for the address at once.
The person's own settings are GET /me/community-settings and PATCH (or PUT, the same): add_policy (anyone, follows_and_shared, nobody), quiet_hours: { enabled } (10pm to 7am local), show_on_profile, show_on_leaderboards (community leaderboards) and timezone (an IANA name, UTC until set). GET /me/communities lists the caller's communities, pinned first, with their role, alert settings and any paid membership.
Money
Community money is integer cents, USD. Dues and gifts are paid to the community's own Stripe Express account, which the owner connects with POST /communities/{id}/stripe/onboarding (GET …/stripe/status for the owner and leaders; POST …/stripe/dashboard-link). FundlyHub keeps 0% and passes Stripe's card fee through. Dues and fund gifts are not donations and are not tax-deductible.
Paid membership
| Endpoint | Auth | Notes |
|---|---|---|
GET /communities/{id}/membership | Public | The plan: price_cents, yearly_price_cents, perks, leaders_join_free, payee_name, pending_change, accepting_payments, fee_preview, tax_note: "not_tax_deductible". |
PATCH /communities/{id}/membership | Owner | Monthly 100–100,000 cents, yearly 100–1,000,000, up to 8 perks of 120 characters. New joiners pay a new price at once; a paying member moves to it at their first renewal 30 days or more after the notice email. Going free cancels every subscription at period end. |
POST /communities/{id}/join/paid | Signed in | { "interval": "month" | "year" } (month when omitted). Answers { status, intent_type, client_secret }. |
GET /communities/{id}/membership/me | Signed in | The caller's paid membership: status, price, renewal, card, and the open invoice's client_secret while payment is due. |
POST …/membership/cancel · …/resume | Signed in | Cancel at period end (access lasts until access_until; one never charged ends at once), or undo that before the period ends. |
GET /me/community-memberships · …/{membershipId}/invoices | Signed in | Live paid memberships, and their paid and open Stripe invoices. |
When the community asks for approval (private, or join_approval: leaders), the paid join files the request and returns a SetupIntent (intent_type: "setup") to save a card: nothing is charged until a leader approves. Otherwise it returns the first invoice's PaymentIntent (intent_type: "payment"), and the person is a member once it is paid. With leaders_join_free (the default) the owner, leaders and volunteers are members without paying. Refusals: 409 NOT_PAID_COMMUNITY, PAYMENTS_NOT_READY (the community's Stripe account cannot take charges yet), INTERVAL_UNAVAILABLE, ALREADY_MEMBER, and 403 REMOVED.
The community fund
A paid community's owner switches the fund on with PATCH /communities/{id}/fund (enabled, visibility, accept_gifts; a free community gets 409 NOT_PAID_COMMUNITY). Dues and one-time gifts come in; the owner gives from it to Fundlies or withdraws it. visibility is public (anyone), members (paying members, the owner and leaders) or private (the owner and leaders). Anyone else gets only the settings and viewer from GET /communities/{id}/fund, and 403 FUND_HIDDEN from GET …/fund/entries. Dues show as one row a month, never per member; an anonymous giver is named to the owner and leaders only.
| Endpoint | Who | Notes |
|---|---|---|
POST /communities/{id}/fund/gifts | Anyone, guests too | amount_cents 100–10,000,000, note?, anonymous?, donor_name?, and donor_email for a guest. Needs a reCAPTCHA token (recaptcha_token or x-recaptcha-token) unless the caller is a signed-in session with a verified email; an API key is not exempt. Returns a PaymentIntent client_secret, fee_cents and net_cents. |
GET …/fund/allocation-check · POST …/fund/allocations | Owner | Give to a Fundly, as a donation from "<Community> fund"; never to one the owner organizes, co-organizes or benefits from. Send an Idempotency-Key so a retry is a no-op. |
POST …/fund/withdrawals/code · POST …/fund/withdrawals | Owner | A payout to the community's bank, with a reason (up to 120 characters) and a 6-digit code emailed to the owner: valid 10 minutes, 5 tries, at most 5 codes an hour. |
GET …/fund/entries.csv | Owner, leaders | Every entry, as CSV. |
GET /me/community-funds/pay-options?fundraiser_id= | Signed in | Funds the caller owns that may give to this Fundly. |
API keys cannot move community money
Stripe onboarding, the Stripe dashboard link, allocations, withdrawal codes and withdrawals need a signed-in session (session cookies or a Cognito ID token). An API key gets 403 SESSION_CREDENTIAL_REQUIRED.
Errors
Refusals are { "error": "…", "code": "…" }, sometimes with more (field, allowed, suggestion, checkout, cancel_path, blockers).
| Status | Codes |
|---|---|
400 | VALIDATION_ERROR (with field, allowed or details), TOO_MANY, PRIMARY_REQUIRED |
401 | No credentials |
402 | PAYMENT_REQUIRED: a paid community, use the paid join |
403 | FORBIDDEN (the caller's role cannot), MEMBERS_ONLY, REMOVED, NOT_A_MEMBER, NOT_YOUR_INVITE, NOT_OWNER, NOT_LEADER, FUND_HIDDEN, EMAIL_NOT_VERIFIED, SESSION_CREDENTIAL_REQUIRED |
404 | NOT_FOUND, INVITE_INVALID; NOT_A_MEMBER from /communities/{key}/me |
409 | SLUG_TAKEN, LIMIT_REACHED, LEADER_LIMIT, NOT_A_LEADER, OWNER_MUST_TRANSFER, PAID_MEMBERSHIP_ACTIVE, COMMUNITY_NOT_ACTIVE, HAS_MONEY, NOT_A_MEMBER (leave), and the money codes above |
410 | INVITE_INVALID: the invite expired or was used |
429 | Rate limited; RESEND_TOO_SOON; STEP_UP_RATE_LIMITED and STEP_UP_LOCKED on withdrawal codes |
Rate limits
- The public reads (the directory,
/communities/top,/home/featured-communities,/users/{id}/communities, a community and itsabout,feed,fundlies,members,membership,fundandfund/entriesreads) take the public limiter, 300 a minute per IP, and skip the global one. The invite preview and the form rules take the public limiter and the global 100 a minute per IP as well. - Most signed-in writes take the authenticated limiter: 100 a minute per account.
- On top of that: adds and personal invites, 50 per person in any 24 hours; a resend, once a day per invite; withdrawal codes, 5 an hour.
See Rate Limits.
Related
- Cities: a city page lists the listed communities placed in it.
- Fundraisers
GET /leaderboard?community=<slug>ranks one community's members.- Communities reference