Non-profits API
Find non-profits, read their pages, add a 501(c)(3) and get it verified, give to its general fund, and run its team.
A non-profit is an organization
A non-profit is an organization record with kind: "nonprofit", now the only kind there is: the database accepts no other kind, and POST /organizations answers 410 with href: "/nonprofits/new". New pages come from the add flow. One record, with one id and slug, serves every surface: /nonprofits/* (this page) is the non-profit read model, /organizations/* returns the older profile of the same rows (legal_name, verification_status, stats, updates), and /org-admin/{slug}/* is the team's own surface, including the non-profit team settings. legal_name and ein come from the IRS record and the team cannot change them (422, code: "locked"). One EIN has one page.
Who can call what
| Calls | Credential |
|---|---|
| The directory, a page and its tabs, reading an invite, the giving policy, a gift quote, a gift checkout, link clicks | None. Signing in fills in viewer, lets a page's team read it before it is public, and links a gift to the donor's account. |
Follow and unfollow, withdrawing a join request, accepting or declining an invite, GET /me/nonprofit-beneficiaries | Signed in |
| Asking to join, reporting a page, every call of the add flow | Signed in with a verified email (403, code: "EMAIL_NOT_VERIFIED") |
The team settings under /org-admin/{slug} | Signed in, with the team role that holds the permission |
"Signed in" is session cookies, a Cognito ID token, or an API key (Authorization: Bearer fh_live_…) acting as its owner with every permission the owner holds; see Authentication. Most of these endpoints answer without a data envelope; lists (the directory, Fundlies, activity, drafts, links, programs, GET /me/nonprofit-beneficiaries) and the giving endpoints use data.
Status and who can see a page
status | Meaning | Readable by |
|---|---|---|
draft | Being added, not submitted | Its owner |
under_review | Submitted; FundlyHub is reviewing it | Its team (any role) |
verified | Approved by FundlyHub | Everyone |
paused | Verified, but donations are paused by a failing check or by FundlyHub | Everyone. The page shows donations_paused: true and no reason. |
rejected, suspended | Decided by FundlyHub | Its team |
Anyone else gets 404 (code: "not_found") from the page, its tabs and its giving endpoints, so a hidden page is never confirmed to exist. Approval, rejection, suspension and FundlyHub's own pauses are not part of this API.
The directory
Lists verified and paused pages only, paused ones last; never drafts or pages under review.
| Query | Notes |
|---|---|
kind | nonprofit (default) leaves churches out, church lists only churches, all lists both. See Churches. |
q | 2 characters or more. Matches the display, legal and DBA names and the mission; a value with exactly 9 digits (12-3456789 or 123456789) also matches the EIN. |
cause | animals, arts_culture, children_youth, community_development, disaster_relief, education, environment, food_security, health, housing_homelessness, human_rights, immigrant_refugee, mental_health, seniors, veterans, women_girls, religious or other. |
city | A city (place) slug. |
sort | impact (default, most raised first), newest (most recently verified) or name. |
limit, offset | Default 24, at most 48; default 0. |
An unknown kind, sort or cause is a 422 whose code names the parameter. The answer is { data, pagination: { total, limit, offset }, facets: { causes: [{ key, count }], cities: [{ slug, name, count }] } }.
Each card carries id, slug, display_name, logo, banner_image, cause, place, mission, status, followers, active_fundlies (live and not fully funded), is_church, viewer ({ role, following }; a guest's is { role: null, following: false }) and:
deductible: Publication 78 lists it as a public charity (PCorPOF), or the EO Business Master File gives it deductibility code 1.impact_cents: raised on its own Fundlies (counted gifts after the Stripe fee, never the tip). General-fund and monthly gifts are not in it.
facets.causes ignores the cause filter and facets.cities (at most 50) ignores city; pagination.total counts the filtered set.
A non-profit's page
Takes the slug, an old slug or the id; an old slug answers with the current one in slug. The response is the card plus legal_name, ein (12-3456789), website, founded_year, ruling_year, links, programs, counts, impact (raised_cents, fundlies, donors), city_page, donations_paused, general_fund ({ enabled, visibility, monthly_gifts_enabled }) and:
contact_emailonly when the team made it public, or to the team;address_publicis only the{ city, region }of the mailing address.tax:irs_status_label,deductible,ruling_year,ca_registry_status,last_checked_at,irs_record_url,form990_url,sources(pub78,eo_bmf: the IRS lists whose latest check passed) anddetermination_letterwhen the team shows an approved one.viewer:signed_in,role,title,following,join_requestandcan(edit_page,manage_team,start_fundly,approve_fundlies,read_finance,manage_payouts,transfer_ownership,see_fund). Usecanto decide what to show; every endpoint still checks.
| Endpoint (same visibility as the page) | Returns |
|---|---|
GET /nonprofits/{slug}/fundlies | Its own Fundlies, never a team member's personal one: { data, counts: { active, completed }, pagination }. status active (default), completed or all; sort newest, most_raised or ending; limit default 12, at most 48. |
GET /nonprofits/{slug}/team | Members shown on the page, grouped leadership, staff, volunteers; hidden_count; followers and up to 5 public followers. |
GET /nonprofits/{slug}/activity | Updates, Fundlies launched, 25/50/75% milestones and goals reached, newest first. limit default 10, at most 50. |
GET /nonprofits/{slug}/impact | raised_cents, fundlies, donors, since, a breakdown of its counted Fundlies (at most 200) and its city. |
GET /nonprofits/{slug}/documents/{docId} | A document FundlyHub approved and the team shows, never a W-9 or bank document. PDFs and images open inline. |
| Endpoint | Auth | Notes |
|---|---|---|
POST / DELETE /nonprofits/{slug}/follow | Signed in | { following, followers }. Unfollowing twice is fine. |
POST /nonprofits/{slug}/join-requests | Verified email | { note? } (500 characters) → 201 { id, status: "pending" }; the owner and admins are emailed. 409 already_member or already_requested; a draft is 404. |
DELETE /nonprofits/{slug}/join-requests/mine | Signed in | 204, also when there is nothing to withdraw. |
POST /nonprofits/{slug}/report | Verified email | { category, details? }; a repeat report replaces the earlier one. |
POST /nonprofits/{slug}/links/{linkId}/click | None | One count per link per UTC day, no user ids. Always 204. |
Adding a non-profit
Every call needs a verified email. A draft answers only to its owner (anyone else gets 404), and the calls on one draft take its id, not its slug.
1. Look up the EIN
POST /api/v1/nonprofits/lookup { "ein": "12-3456789" }
Dashes and spaces are ignored; anything but 9 digits is 422 invalid_ein. Lookups and draft creation share 20 per hour per person (429, code: "rate_limited"). The answer is 200 with outcome, ein, irs (the IRS record or null) and, for some outcomes, reason or existing. The first matching outcome wins:
outcome | Meaning | Next |
|---|---|---|
existing | A submitted page has the EIN; existing is its card, with your own viewer.role and viewer.join_request. | Ask to join, or report a wrong claim { ein, details? }. |
revoked | On the IRS auto-revocation list, not reinstated. | Create the draft with route: "reinstatement"; submitting needs a reinstatement_letter document. |
verified | A 501(c)(3) public charity (Publication 78 PC or POF, or deductible and not a private foundation in the EO BMF) that is not a church or in a group exemption. | Create the draft. |
manual_review | A 501(c)(3) church, group-exemption member or private foundation (reason), or one the rules cannot place (no reason). | Create the draft; FundlyHub reviews it by hand. |
not_eligible | In the IRS data, but not a 501(c)(3), or not deductible. | It cannot have a page. |
not_found | In none of the IRS datasets FundlyHub loads. | POST /nonprofits/notify-me { ein }: one email once a later monthly IRS load makes it addable. |
2. Create the draft
POST /api/v1/nonprofits { "ein": "12-3456789" }
Creates the page as a draft with you as its owner: 201 { id, slug, status: "draft", step: 2 }. The legal name and IRS facts are copied from the IRS record, the slug is made from the name and the cause is suggested from the NTEE code. Your own unfinished draft for the same EIN comes back with 200; GET /nonprofits/drafts/mine lists them. 409 codes: ein_taken (details.existing; a draft nobody has saved for 30 days no longer holds the EIN and is released instead), not_eligible (also revoked without route: "reinstatement"), not_found, and too_many_drafts (5 unfinished drafts, details.max).
3. Show that you speak for it
| Endpoint | Body | Result |
|---|---|---|
POST /nonprofits/{id}/authority/email | { email, website? } | 202 { sent_to }: a 6-digit code to an address at the website's domain or a subdomain, never a free email service (422 free_email_domain, domain_mismatch; website_required if the draft has no website and you sent none). 5 codes an hour. |
POST /nonprofits/{id}/authority/email/verify | { code } | 15 minutes, 5 tries (422 bad_code with details.attempts_left, expired, too_many_attempts). Authority is verified only at a domain FundlyHub verified for this organization, otherwise pending for FundlyHub to decide. |
POST /nonprofits/{id}/authority/form990 | { name_on_990, title } | pending: FundlyHub checks the name against the latest Form 990. |
POST /nonprofits/{id}/authority/letter | { document_id } | pending. Upload the letter first: POST /org-admin/{slug}/documents with doc_type: "officer_letter". |
POST /nonprofits/{id}/authority/volunteer | none | pending: a claim FundlyHub reviews; it never enables donations by itself. |
The claims answer { authority: { method, status } }. Every call here is 409 already_verified once authority is verified, and every write to a draft is 409 already_submitted after submit. Moving the draft's website to another domain undoes a work-email claim unless the address is at a domain FundlyHub verified. Record your title (up to 120 characters) and attestation: true with PATCH /nonprofits/{id}/onboarding, sending as attestation_text exactly the sentence GET /nonprofits/{id}/onboarding returned (422 title_required or required; 409 attestation_changed, with the current sentence in details.attestation_text, if it has changed).
4. The page, receipts and payouts
The same PATCH takes step (1 to 5) and every page setting, and answers what GET onboarding returns: the page plus step, review_route, review_reason, irs, authority, address, receipt, stripe, documents, checks and the attestation sentence. The owner can connect the non-profit's own Stripe account while it is a draft, with POST /org-admin/{slug}/payouts/connect (stripe.flag_on says whether organization payouts are switched on).
5. Submit
POST /api/v1/nonprofits/{id}/submit { "terms_accepted": true }
Records the terms, runs every check, moves the page to under_review and answers it. Not ready is 422 incomplete, with details.missing listing what is left: authority (none, or rejected), title, attestation, display_name, place, cause, mission, address (line 1, city, region, postal code), receipt_signer_name, receipt_signer_title, reinstatement_letter (reinstatements only), terms_accepted. FundlyHub then approves (verified) or rejects the page, and approves only once authority is verified, so a pending claim is decided in that review.
Deleting a draft
DELETE /api/v1/nonprofits/{id} → 204, for the owner of an unsubmitted draft only. Send the draft's id: a slug is 404, as is someone else's draft. A submitted page is 409 already_submitted and cannot be deleted through the API. The draft is soft-deleted and its address released.
Verification checks
FundlyHub checks a page at lookup, at submit, about once a week while it is submitted and not rejected or suspended, when FundlyHub asks, and on POST /org-admin/{slug}/verification/check-now (once an hour; else 429 too_soon with details.retry_after_seconds).
source | pass | warn | fail |
|---|---|---|---|
pub78 | Listed as PC or POF | Not listed, or another code | Never |
eo_bmf | A 501(c)(3) with deductible contributions | Not listed | Listed as anything else |
revocation | Not revoked, or reinstated | Revoked, not reinstated | |
ca_registry | current or not_required | current, renewal due within 30 days | delinquent, suspended, revoked |
stripe | Ready | Onboarding unfinished, or requirements past due | Stripe disabled an onboarded account |
authority | verified | pending | rejected |
skipped means nothing to check: an IRS dataset not loaded yet, no CA Registry status recorded, no Stripe account, no authority recorded. A fail pauses donations on a submitted page (a verified page then reads status: paused); the next run without a fail lifts it, but a pause FundlyHub set stays until FundlyHub lifts it. GET /org-admin/{slug}/verification shows the newest check per source, next_check_at, documents, the IRS record and the authority claim.
Churches
A church is a non-profit, not a separate type: the same endpoints, roles, review and money rules apply. is_church is worked out by FundlyHub and changes neither tax eligibility nor permissions. A page is a church when the EO BMF gives it foundation code 10, its EIN lookup sent it to review with reason: "church", its NTEE code is in X20 to X29, or its display, legal or DBA name contains the word church, chapel, cathedral, parish, iglesia, церква or церковь (a mission that mentions churches does not count). It matters in four places:
- Directory.
GET /nonprofitsleaves churches out unlesskind=churchorkind=all, and so does a city's non-profit count. - EIN lookup. Foundation code 10 is never
verifiedat lookup, even with a Publication 78 listing: it ismanual_reviewwithreason: "church". - IRS lists. A missing Publication 78 listing is only a
warn, so a church Pub 78 does not list is not paused for it; theeo_bmfcheck decides. A church in none of the IRS datasets isnot_foundand cannot be added through this API. - Receipts. With foundation code 10 the acknowledgment says "Only intangible religious benefits were provided in exchange for this contribution." instead of "No goods or services were provided in exchange for this contribution." This follows the IRS code, not
is_church.
Giving to the general fund
A gift straight to the non-profit rather than to one of its Fundlies: US dollars only, integer cents, no reCAPTCHA, no sign-in needed.
| Step | Endpoint | Notes |
|---|---|---|
| 1 | GET /nonprofits/{slug}/giving-policy | { data: { org_id, slug, currency: "usd", can_give, monthly_enabled, unavailable_reason, limits } } |
| 2 | POST /nonprofits/{slug}/gift-quote | Optional. Exactly { amount_cents, tip_cents?, cover_fee?, frequency? }; reserves nothing. |
| 3 | POST /nonprofits/{slug}/gifts | Reserves the gift and creates its PaymentIntent; no card is charged yet. 5 a minute per IP. |
| 4 | Stripe.js | Confirm the client_secret. |
| 5 | POST /payments/confirm | { payment_intent_id } settles the gift; Stripe's webhook to FundlyHub settles it too. |
unavailable_reason when can_give is false | What is missing |
|---|---|
nonprofit_not_accepting | The page is not verified (paused, under review, …). |
payments_disabled | FundlyHub has not switched payments on, for the platform or for this non-profit. |
nonprofit_account_not_ready | Its Stripe account cannot take charges and payouts yet, or its payouts are paused. |
fund_disabled | The team has not set general_fund_enabled. |
receipt_identity_incomplete | The EIN or legal name a receipt needs is missing. |
monthly_enabled also needs FundlyHub to allow monthly gifts and the team's monthly_gifts_enabled. general_fund.visibility only sets the page's viewer.can.see_fund; giving does not check it. The current limits: gift_min_cents 100, gift_max_cents 10000000, preset_cents[2500, 5000, 10000, 25000], default_cents 5000, note_max 280, donor_name_max 200. Read them from the policy rather than hard-coding them.
| Quote field (cents) | Meaning |
|---|---|
donation_cents | The gift. |
tip_cents | The voluntary tip to FundlyHub. |
covered_fee_cents | With cover_fee: true, what the donor adds so the processing fee does not come out of the gift; else 0. |
total_cents | What the card is charged: donation_cents + covered_fee_cents + tip_cents. |
processing_fee_cents | The processing fee on total_cents. |
receipt_amount_cents | The contribution the receipt acknowledges: donation_cents + covered_fee_cents, never the tip. |
nonprofit_net_cents | What reaches the non-profit: receipt_amount_cents - processing_fee_cents. |
A monthly quote adds application_fee_percent, the rate Stripe Billing applies each month.
const API_BASE = 'https://api.fundlyhub.org/api/v1';
const res = await fetch(`${API_BASE}/nonprofits/kalyna-family-aid/gifts`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
credentials: 'include', // optional: links the gift to a signed-in donor
body: JSON.stringify({
checkout_key: crypto.randomUUID(), // reuse only to retry this exact request
amount_cents: 5000, // $50.00
tip_cents: 0,
cover_fee: true,
frequency: 'once',
donor_name: 'Jane Smith', // required, even with is_anonymous: true
donor_email: 'jane@example.com',
is_anonymous: false,
note: 'For the pantry' // optional, up to 280 characters
})
});
const { data } = await res.json();
// client_secret, payment_intent_id, receipt_id, frequency, quote,
// amount_cents (= total_cents), stripe_fee_cents, net_amount_centsThe body also takes monthly_consent and donor_locale; any other key is 422. donor_name and donor_email address the receipt, so they are required even for an anonymous gift, whose donation record then stores neither. Repeating the identical request with the same checkout_key returns the same reservation and PaymentIntent; anything changed needs a new key (409 checkout_key_conflict). The charge goes to the non-profit's own Stripe account, with tip_cents + processing_fee_cents as FundlyHub's application fee, and never falls back to anyone's personal account: a non-profit that cannot take the gift is a 409 with one of the reasons above, monthly_gifts_disabled or nonprofit_account_changed.
Each gift is also a donation, with no fundraiser_id: pending at checkout, paid once settled, amount_cents the receipt amount, tip_amount_cents the tip, fee_amount_cents the processing fee. Gifts to one of the non-profit's Fundlies go through POST /payments/create-intent with fundraiser_id and a checkout_key instead; see Donations.
Monthly gifts
frequency: "monthly" needs monthly_consent: true (422 monthly_consent_required). The first month is charged at checkout, by card; once it is paid, Stripe Billing charges the same total_cents monthly from a month later until it is stopped. Monthly giving is general-fund only. While the non-profit cannot take gifts, nothing is charged and the gift is paused; it resumes when that clears, and stops for good if the block lasts 30 days or the non-profit's payout account changes. POST /donations/receipt/{receiptId}/nonprofit-monthly/cancel, with the receipt id or the PaymentIntent id, stops future months, refunds nothing and is safe to repeat.
Receipts
At checkout FundlyHub freezes the receipt identity: the legal name from the IRS record, the EIN, the tax status, the mailing address, the goods-or-services statement (see Churches) and the signer and thank-you text from the page settings. Later page edits never change it. Once the gift is paid and has reached the non-profit, the receipt emailed to donor_email carries this acknowledgment, the contribution (receipt_amount_cents) and the line "The voluntary FundlyHub tip is excluded from this acknowledgment." GET /donations/receipt/{receiptId} takes the checkout's receipt_id or the PaymentIntent id and adds nonprofit_receipt (the snapshot), nonprofit_receipt_adjustment.state (valid, partial_refund, refunded, disputed, void or review; check it before relying on the receipt) and nonprofit_monthly. Both ids are secrets: the receipt holds the donor's email.
Fundlies for a non-profit
A Fundly raises for a non-profit when POST /fundraisers sets org_id to the non-profit's id. The organizer needs a team role that can start Fundlies (owner, admin or fundraiser; else 403 nonprofit_team_permission), the non-profit must be verified, not paused (409 nonprofit_not_verified), and the Fundly must be in USD (422 nonprofit_currency_unsupported). type: "charity" without a non-profit is 422 nonprofit_beneficiary_required. These are the "own Fundlies" the page counts; a member's personal Fundly never is one. GET /me/nonprofit-beneficiaries is the picker: { data: [{ id, name, slug, logo, role, can_start, reason }] } for each non-profit you are on the team of, with reason team_permission or not_verified when can_start is false. Raising for a person is a separate flow (GET /me/person-beneficiaries and beneficiary invitations); one Fundly cannot name both a person and an organization (422 beneficiary_person_type).
Team settings
The team's endpoints live under /org-admin/{slug}/ and take the page's current slug (an old slug or the id is 404). Without the permission the answer is 403 with "message": "Requires permission: …".
| Role | What it can do |
|---|---|
owner | Everything, including payouts and handing over ownership. Never more than one. |
admin | Edit the page, manage the team, start Fundlies, read the finances. |
fundraiser | Start Fundlies; read the team area. |
viewer | Read the team area and the finances. |
member | Listed on the team, hidden from the page by default. No access to money or settings. |
| Endpoint | Permission (roles) | Notes |
|---|---|---|
GET nonprofit/attention | org.read (owner, admin, fundraiser, viewer) | Counts of join_requests, invites_waiting, stripe_requirements, registry_renewal, check_failed, authority_pending, each with an href, and month: raised, gifts and donors since the 1st over its own Fundlies and its general-fund and monthly gifts. |
GET / PATCH nonprofit | org.update_settings (owner, admin) | The page settings. |
GET / PUT links | org.update_settings | { links: [{ id?, url, label? }] } replaces the ordered list: up to 8, labels up to 40 characters, a row sent with its id keeps its clicks. URLs are normalized, de-duplicated and checked for unsafe sites; one FundlyHub removed cannot come back. A bad row is 422 with details.index and details.reason. |
GET / PUT programs | org.update_settings | { programs: [{ id?, title, description?, icon? }] }, up to 12; titles up to 80 characters, descriptions up to 300. |
GET team | org.read | { members, invites, join_requests, roles_help }; emails, invites and join requests only for the owner and admins. |
POST invites, resend, DELETE invites/{inviteId} | nonprofit.team.manage (owner, admin) | See below. |
POST join-requests/{requestId}/approve, decline | nonprofit.team.manage | See below. |
POST transfer-ownership | nonprofit.team.manage, owner only | { user_id } of an admin (422 not_admin, 422 self, 403 not_owner); the old owner becomes an admin. { owner, previous_owner }. |
GET verification | org.read | W-9 and bank documents only with org.upload_documents (owner, admin); the authority email only for the owner. |
POST verification/check-now | org.update_settings | Once an hour; answers as GET verification. |
Documents, payouts, funds and removing a member are the general Organization Admin endpoints.
Page settings
PATCH /org-admin/{slug}/nonprofit and the add flow's PATCH take the same optional fields (unknown keys are ignored) and answer the page: display_name (up to 120 characters), logo and banner_image (https links), cause, mission (up to 280), website, contact_email, contact_email_public, founded_year, place ({ place_id } or { name, region, country, lat?, lng? }; a new city applies to Fundlies launched afterwards), address ({ line1, line2, city, region, postal_code, country }, the private mailing address receipts print), receipt_signer_name and receipt_signer_title (up to 120), receipt_thank_you (up to 600), year_end_summary, general_fund_enabled, general_fund_visibility, monthly_gifts_enabled and links (the whole list). legal_name and ein are 422 locked. PATCH /org-admin/{slug}/settings refuses a non-profit's website (422 use_nonprofit_settings): change it here, or through the add flow while the page is a draft.
Invites and join requests
- Invite
{ emails, role, title? }: up to 20 addresses,roleadmin,fundraiser,viewerormember(ororg_adminand the other RBAC spellings; never owner),titleup to 80 characters. Each address gets a link to/nonprofits/invite/{token}on the FundlyHub website, good for 30 days.201 { created, skipped }(already_member,already_invited,invalid); nobody grants above their own role (403 above_own). Resend: a new token and 30 more days, 5 sends at most (409 max_sends). Cancel is idempotent (409 acceptedonce accepted). - The invited person reads it with
GET /nonprofits/invite/{token}(public: the page, role, title, a maskedemail_hint,state, andviewer.email_matcheswhen signed in), then accepts{ show_on_page? }or declines. One of the caller's verified emails must be the invited address (403 email_mismatch). Accepting joins with the invite's role and title, on the page asshow_on_pagesays or by the role's default (shown, except amember), and emails the inviter. Both answer{ slug }; repeating your own accept or decline answers the same, and an invite that can no longer be used is409with its state (expired,accepted,revoked,declined) as thecode. - Join requests. Approve with
{ role, title? }(roleismemberwhen omitted): the person joins, is emailed, and the answer is the member. Decline answers204. A request already decided or withdrawn is409.
Changing a member
PATCH /org-admin/{slug}/members/{userId} (org.manage_members: owner, admin) applies the non-profit rules when the body has title or show_on_page, or a role such as admin or fundraiser: { role?, title?, show_on_page? }, title up to 80 characters or null to clear. It answers the member. A role of owner is 422 transfer_ownership. Nobody grants above their own role (403 above_own), changing someone else needs a role above theirs (only the owner changes an admin), and the owner stays owner until ownership is transferred (422 last_owner). Remove someone with DELETE /org-admin/{slug}/members/{userId}.
Errors
The non-profit endpoints refuse with:
{
"error": {
"code": "locked",
"message": "legal_name is set from the IRS record. Ask FundlyHub to change it.",
"details": { "kind": "LOCKED", "field": "legal_name", "reason": "locked" }
}
}code is the reason to branch on (ein_taken, locked, email_mismatch, too_soon, fund_disabled and the others on this page). details.kind is VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, CONFLICT, LOCKED, RATE_LIMITED or UNPROCESSABLE; a field error adds field and reason, a list row index. A malformed body on the giving endpoints is 422 with code: "validation_error" and the field errors in details.
Refusals made before the handler runs keep the API's flat shape ({ "error": "…", "message": "…" }): a missing credential (401), an unverified email (403, code: "EMAIL_NOT_VERIFIED"), a missing team permission (403), an unknown slug under /org-admin (404, "error": "Organization not found") and the rate limits (429), except the EIN lookup budget, whose 429 is code: "rate_limited" in the shape above. POST /fundraisers and POST /payments/create-intent report non-profit refusals as { "error": "<message>", "code": "<reason>" }.
200,201,202(authority code sent),204— Success401— Not signed in403— Email not verified, missing team permission,email_mismatch,above_own,not_owner404— Not found, not visible to you, or not your draft409— A state conflict:ein_taken,already_submitted,already_verified,already_member,checkout_key_conflict, the giving refusals422— A field failed,locked,incomplete,monthly_consent_required,invalid_amount429— A rate limit, ortoo_soon500— Server error
Reference
| Reference section | Operations | About |
|---|---|---|
| Non-profits | 37 | Non-profit organizations on FundlyHub: the directory, a non-profit's page and its tabs (Fundlies, team, activity, impact, public documents), following, link clicks and reports, joining the team by request or invite, giving to its general fund (the giving policy, a quote and checkout), the non-profits a signed-in person may start a Fundly for, and the add flow: an EIN lookup, a draft, proof of authority to act for the organization, and submission for review. A page's `{slug}` takes its current slug, an old one or its id; the add flow's paths take the id. A draft is visible only to its owner, and a page under review, rejected or suspended only to its team and staff; anyone else gets `404`. These endpoints' own refusals come as `{ "error": { "code", "message", "details" } }`, where `code` is the reason to branch on. |
| Non-profits · Team settings | 16 | A non-profit's own team at work, under `/org-admin/{slug}`: what needs attention, the page's settings, links and programs, the team with its invites, join requests and ownership transfer, and the verification and tax status with an on-demand re-check. Every operation needs a signed-in session and an org-scoped permission on that organization, as under Organization Admin: `org.read` for the read-only views, `org.update_settings` for the page's settings, links and programs, and `nonprofit.team.manage` (the owner and admins) for the team. Only the owner transfers ownership, and only to an admin. An organization that is not a non-profit answers `404`. |
- Non-profits: the directory, the page and its tabs, follow, join requests, invites, the add flow, general-fund giving (policy, quote, checkout) and your non-profit choices.
- Non-profits · Team settings: the team's
/org-admin/{slug}endpoints. - Stop monthly gifts, under Donations.
- Related: Organizations · Organization Admin · Donations · Fundraisers · Authentication · Roles & Permissions