Skip to content

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 sectionOperationsAbout
Communities82Communities, 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.

FieldNotes
id, slug, name, hrefhref is the site path, /communities/<slug>.
kindcity, church, diaspora, families, school, workplace or other (the default).
city_text, place_id, place_slugThe city as typed, the city it was placed in, and that city's slug when its page exists.
photo_url, avatar_urlImages uploaded to FundlyHub, or null.
visibilitypublic, or private: the feed and member list are for members, and joining needs approval.
listedfalse keeps it out of the directory and city pages; it stays reachable by link.
membership, price_cents, yearly_price_cents, currencyfree or paid; monthly and yearly dues in integer cents; usd.
join_approvalnone, or leaders: every join is a request.
statusactive; draft (seen by its owner only); hidden or suspended, set by FundlyHub and seen by members only. A suspended community is read-only.
featuredPicked by FundlyHub.
member_count, fundly_countActive members, and the verified Fundlies posted here.
impact_centsCommunity 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.
viewerThe 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 ​

EndpointPurpose
GET /communitiesThe directory.
GET /communities/topTop 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-communitiesFeatured first, then the biggest. limit default 4, max 12.
GET /communities/{key}The community page (below).
GET /communities/{key}/aboutThe About tab: about, links, city_page, languages, guidelines, kind, the plan, stats and team.
GET /communities/{key}/fundliesThe Fundlies posted here.
GET /communities/{key}/feedThe feed. Members only in a private community.
GET /communities/{key}/membersThe members. Members only in a private community.
GET /users/{id}/communitiesA 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-rulesEvery 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.

QueryNotes
qCase-insensitive substring of the name, city_text or about. Ignored under 2 characters.
categoryall (default), paid, or a kind. Anything else is a 400 with allowed.
sortfeatured (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, offsetlimit default 24, max 48; offset default 0.
bash
curl "https://api.fundlyhub.org/api/v1/communities?category=church&limit=1"
json
{
  "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, and links: 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, …), or null. Link to /cities/<slug> only when has_page.
  • The settings: share_policy, add_policy, default_alert, show_leaders, perks, leaders_join_free.
  • stats: member and Fundly counts, impact_cents with its four parts in impact (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 when show_leaders is off and the caller is not the owner or a leader.
  • pinned_post, or null: also null for anyone the feed refuses (a non-member of a private community), since a pinned post is a feed post. Its author is null when 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) and can, the permissions the caller holds here.
  • invite: the caller's own share link (active members); setup, the owner's checklist; suspended_reason for the owner and leaders.

Fundlies, feed and members ​

TabQueryReturns
Fundliesstatus: 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.
Feedbefore: 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).
Membersrole: 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 ​

EndpointAuthNotes
POST /communitiesSigned in, verified emailThe 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, leadersThe 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}/linksOwner, leadersThe 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}OwnerA 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}/reportSigned 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}/clickPublicA 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.

RoleAdds to the role below
memberShares their own Fundlies, has their own invite link, and may add people when add_policy is members.
volunteerAdds and invites people, approves join requests, posts.
leaderEdits settings and links, changes roles below leader, removes volunteers and members, pins posts, approves shared Fundlies.
ownerMakes 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.

EndpointWho
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}/transferThe 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-countsOwner, 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_actionMeaning
joinPOST /communities/{key}/join joins at once.
requestPrivate, or join_approval: leaders: the same call files a request.
payPaid membership: use POST /communities/{id}/join/paid.
accept_inviteThe caller holds a pending invite; joining accepts it, with its role.
joined, requestedAlready a member; request pending.
noneNot 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.

EndpointNotes
POST /communities/{key}/leaveLeaves, 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 · …/denyOwner, 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-link returns { token, url, uses, requires_approval, expires_at }; POST …/invite-link/rotate replaces the code; PATCH …/invite-link (owner and leaders) sets requires_approval and expires_in_days (1, 7, 30, 90 or null). Below leader, a link follows the community's approval rule.
  • Personal invites. POST /communities/{key}/invites takes emails, user_ids and a role (member by 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 the member role. GET …/invites lists the pending ones (owner, leaders, volunteers); POST …/invites/{inviteId}/resend sends 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 …/accept joins: a share link behaves exactly like join with that code, a personal invite joins with its role. POST …/decline declines a personal invite. An invite addressed to an account works only for that account (403 NOT_YOUR_INVITE); an expired or used one is 410 INVITE_INVALID; a member invite into a paid community is 402.

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 ​

EndpointWho
POST /communities/{key}/postsOwner, 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:

json
{ "communities": [ { "community_id": "st-marys-sacramento", "primary": true } ] }
  • Organizer only. community_id takes an id or a slug. At most 3 (400 TOO_MANY), exactly one primary (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_policy is auto or the organizer is its owner or a leader. Otherwise it waits for the owner or a leader: GET /communities/{key}/pending-fundlies, then POST …/fundlies/{fundraiserId}/approve or …/reject.
  • A cleared share is posted, and the members alerted, once the Fundly has passed verification (status active, public, not deleted). Until then GET /fundraisers/{id}/communities shows each share's awaiting: leader_approval or verification.
  • For the share step, GET /me/communities/shareable?fundraiser_id= lists the caller's active communities with this Fundly's share state, and GET /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}, carries communities: 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.
  • push is 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 POST to /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.

EndpointAuthNotes
GET /communities/{id}/membershipPublicThe 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}/membershipOwnerMonthly 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/paidSigned in{ "interval": "month" | "year" } (month when omitted). Answers { status, intent_type, client_secret }.
GET /communities/{id}/membership/meSigned inThe caller's paid membership: status, price, renewal, card, and the open invoice's client_secret while payment is due.
POST …/membership/cancel · …/resumeSigned inCancel 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}/invoicesSigned inLive 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.

EndpointWhoNotes
POST /communities/{id}/fund/giftsAnyone, guests tooamount_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/allocationsOwnerGive 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/withdrawalsOwnerA 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.csvOwner, leadersEvery entry, as CSV.
GET /me/community-funds/pay-options?fundraiser_id=Signed inFunds 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).

StatusCodes
400VALIDATION_ERROR (with field, allowed or details), TOO_MANY, PRIMARY_REQUIRED
401No credentials
402PAYMENT_REQUIRED: a paid community, use the paid join
403FORBIDDEN (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
404NOT_FOUND, INVITE_INVALID; NOT_A_MEMBER from /communities/{key}/me
409SLUG_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
410INVITE_INVALID: the invite expired or was used
429Rate 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 its about, feed, fundlies, members, membership, fund and fund/entries reads) 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.

Built with VitePress