Provider quickstart

This guide is for a provider reading its own books with a provider API key. If you are a platform reading the books of providers in a partner relationship, you hold a partner key instead — start at Authentication.

What your key reaches

A provider key is scoped to one provider: yours. It reads that provider’s own books and nothing else, and it is the only kind of key that reaches the balance sheet and cash flow endpoints — a partner key cannot call those at all. See which endpoints each key reaches for the full list.

Two properties are worth knowing before you write any code, because neither is self-evident from a response.

Your key reads every business entity under your provider. If your Flychain organization restricts individual staff to particular entities, those restrictions do not apply to an API key. A key belongs to the organization rather than to a person, so there is no user for us to filter by. Treat the key as reaching everything GET /business_entities returns, and scope access by controlling who holds the key.

API access follows your Flychain account state. If your account is not active — churned, paused, or still onboarding — every call is refused with 403 PROVIDER_NOT_ACTIVE until it is. The same applies to enrollment in the API programme (403 PROVIDER_API_NOT_ENABLED). Both are checked fresh on every request, so a change takes effect on your next call rather than on a schedule: existing keys are not revoked, they stop working while the condition holds and work again once it clears. This is an account state, not an outage — retrying will not clear it, and neither will rotating the key.

Reports are produced per business entity

Two levels, and the distinction is the thing to get right first:

• A provider is your business as a client of Flychain.
• A business entity is a legal entity whose books we keep.

Reports are produced at the entity level, because that is the level a set of books exists at. Most providers are a single legal entity; the distinction exists so a figure is never an accidental blend of two. Both identifiers are stable UUIDs for the life of the account.

Every report path names both:

/external/v1/provider/{provider_id}/business_entity/{business_entity_id}/financial_reports/...

From your first call to a report

1. Find your provider_id

curl https://api.flychain.us/external/v1/providers \
  -H "Authorization: Bearer $FLYCHAIN_API_KEY"

Your key already carries its scope, so this returns a one-element list holding your own record. It is a list rather than a bare object so that a client written against either audience parses the same way — and it is where an integration starts, because every report path needs the provider_id it returns.

{
  "providers": [
    {
      "provider_id": "9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f",
      "legal_name": "Riverbend Pediatric Therapy LLC",
      "dba": "Riverbend Therapy — Northside",
      "other_names": [],
      "tax_id": "123456789"
    }
  ]
}

2. List your business entities

curl https://api.flychain.us/external/v1/business_entities \
  -H "Authorization: Bearer $FLYCHAIN_API_KEY"

Each record carries the business_entity_id a report path takes, plus the four fields that decide whether and how you can report on it:

• reporting_available — whether this entity has books a report can be produced from right now. false covers both an entity still onboarding and one that has been deactivated. Skip these; a report request for one returns 409 BOOKS_NOT_AVAILABLE.
• books_start_date — the earliest date its books cover. Requested ranges are clamped to it.
• books_closed_through — the most recent date a Flychain bookkeeper has finalized the books through. It is the value behind the is_closed flag on every report.
• accounting_basis — CASH or ACCRUAL, a property of the entity rather than a request parameter.

Data semantics covers what each of these does to a figure. Read it before you trust a number.

3. Pull a report

Build the path from the two ids. The parameters differ by report family:

Income statement and cash flow are range reports, and take start_date and end_date (both required, both inclusive, YYYY-MM-DD):

curl "https://api.flychain.us/external/v1/provider/$PROVIDER_ID\
/business_entity/$BUSINESS_ENTITY_ID/financial_reports/income_statement/summary\
?start_date=2026-07-01&end_date=2026-07-31" \
  -H "Authorization: Bearer $FLYCHAIN_API_KEY"

The balance sheet is a position on a date rather than activity over a range, so it takes as_of_date (required) instead:

curl "https://api.flychain.us/external/v1/provider/$PROVIDER_ID\
/business_entity/$BUSINESS_ENTITY_ID/financial_reports/balance_sheet/summary\
?as_of_date=2026-08-31" \
  -H "Authorization: Bearer $FLYCHAIN_API_KEY"

Its monthly variants take an optional months as well (default 12, maximum 36), counting the as-of column: months=12 returns eleven prior month-ends plus the as-of.

Every report echoes back the effective range or date it actually reported on, which is not always the one you asked for. See Data semantics §1.

summary or full

The three report families come in four endpoints each — a single range or date and a monthly series, and each of those in two variants. Twelve report endpoints in all. The two variants cost the same on our side:

• summary returns the report’s totals and nothing else. This is the one to point a recurring pull at.
• The full variant returns the whole statement with per-account detail — the identical structure our own application renders.

The gap is roughly two orders of magnitude of JSON, and it is widest on the cash flow report, whose full variants descend past accounts to individual transactions. Use summary unless you need the detail.

When something is refused

• 404 — for a provider_id or business_entity_id that is not yours. You hold exactly one valid provider_id and GET /business_entities tells you which entities exist, so there is nothing here to distinguish: an id belonging to another provider and an id that never existed are answered identically, on purpose.
• 403 PROVIDER_NOT_ACTIVE / PROVIDER_API_NOT_ENABLED — your account state, as above. Not a credential problem.
• 403 ENDPOINT_NOT_AVAILABLE — you will not see this with a provider key. It is what a partner key gets on a provider-only endpoint.
• 409 BOOKS_NOT_AVAILABLE — the entity exists and is yours, but has no reportable books. It is listed with reporting_available: false.

Data semantics §6 covers these in full, and Authentication covers the credential failures.

Where to go next

1. Data semantics — what the values mean, and the seven places a successful request can still give you a figure you did not intend to use. Read this before trusting a number.
2. Versioning — what may change within v1 and what may not.
3. The API reference — generated from the OpenAPI document we publish as the contract, so it is the authoritative description of every field.