Full balance sheet per month-end
const url = 'https://api.flychain.us/external/v1/provider/9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f/business_entity/3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43/financial_reports/balance_sheet/monthly?as_of_date=2026-08-31&months=12';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.flychain.us/external/v1/provider/9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f/business_entity/3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43/financial_reports/balance_sheet/monthly?as_of_date=2026-08-31&months=12' \ --header 'Authorization: Bearer <token>'Provider keys only. A partner key is refused with 403 ENDPOINT_NOT_AVAILABLE.
One full statement per prior month-end, plus the as-of snapshot, in the same
envelope as monthly/summary.
The largest payload on this API, but not the most expensive request: the whole
series comes from a single call on our side whatever months you ask for, unlike
the monthly income statement. Point a recurring job at monthly/summary anyway —
three integers per column rather than every account of every month — and reach
for this variant when you actually need the detail.
periods holds month-ends only; the as-of snapshot is separate. See
monthly/summary for why.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The provider, from GET /providers or the provider_id on a business-entity
record. With a partner key it must be a provider in your partner relationship;
with a provider key it is always your own provider_id, which GET /providers
returns.
Example
9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2fThe business entity, from GET /business_entities. Must belong to the
provider_id in the same path.
Example
3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43Query Parameters
Section titled “Query Parameters”The date to report the position as of, inclusive.
Same format rules as start_date — a real calendar date, zero-padded, in
YYYY-MM-DD form; 2026-7-1 and 2026-02-31 are both 400 INVALID_REQUEST.
Clamped from both ends, and the response echoes the date it actually used.
Capped at today when it falls in the future, which is the ordinary case for a job
asking for the current month-end every day. Raised to the entity’s
books_start_date when it falls earlier — you get the earliest position we
hold rather than a zero, and as_of_date in the response tells you which date
that is. This differs from the income statement, where a range entirely before
the books is a 400: a snapshot at the books floor is a real opening position,
whereas a range with no books behind it is not a period at all.
Example
2026-08-31How many monthly columns to return, counting the as_of snapshot. months=12
returns eleven prior month-ends plus the as-of.
Clamped to the entity’s books: an entity with four months of books returns four columns however many you ask for. Costs the same on our side at any value — the whole series comes from one call — so the only reason to lower it is payload size.
Example
12Responses
Section titled “Responses”One full statement per month-end, plus the as-of snapshot.
A full statement per month-end, plus the as-of column.
object
The basis an entity’s financials are prepared on.
A property of the entity, not a request parameter. A report is produced on the
basis the underlying books are kept on; there is no per-request switch. It is
returned on every entity record and every report so a figure is never ambiguous,
and it will not change without notice. See guides/data-semantics.
null only where the entity has no books yet — every entity with
reporting_available: true carries a basis.
When this payload was produced, ISO 8601 UTC.
Chronological, one entry per complete month before the as-of date’s
month, up to months - 1 of them. Empty when the as-of date falls in the
entity’s first month of books.
A month-end column carrying the full statement.
object
Month and year of this column, e.g. July 2026.
The date this position is as of — the last day of the month.
Whether a Flychain bookkeeper has finalized the books through end_date.
This is the flag that says a figure is final.
Whether this column’s end_date is in the past. Always true here, because a
month-end column is never the month in progress — the one column that can be
mid-month is as_of, which carries is_closed alone, as whole_period does
on a monthly income statement.
Published as a constant rather than omitted so that a period reads the same on
this report as on the income statement, where the same two flags appear and
is_complete genuinely varies. See guides/data-semantics.
The full statement: three categories, each holding a record with that
category’s total and the accounts beneath it.
This is the identical structure our own application consumes. It therefore
carries accounting metadata (type, sub_type, sort_code, debit_credit)
alongside the figures. Nothing is held back and nothing is added for external
callers — a pared-down copy would be a second definition of the statement, and a
second definition drifts.
object
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
The as-of column carrying the full statement.
object
The effective date, after clamping.
Whether the books are finalized through as_of_date.
The full statement: three categories, each holding a record with that
category’s total and the accounts beneath it.
This is the identical structure our own application consumes. It therefore
carries accounting metadata (type, sub_type, sort_code, debit_credit)
alongside the figures. Nothing is held back and nothing is added for external
callers — a pared-down copy would be a second definition of the statement, and a
second definition drifts.
object
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
One of the three statement categories, holding a record with that category’s
total and the accounts beneath it.
Unlike an income-statement category it carries no presentation hints — there is
no title_tooltip and no percentage on a balance sheet.
object
A node in the full statement: a category root, an account group, or a leaf
account. Recursive through children.
Read total_amount_cents for a total, not amount_cents.
total_amount_cents is the rolled-up figure including every descendant;
amount_cents is only what is posted directly at that node, which for a category
root is usually — but not guaranteed to be — zero.
Null fields are omitted rather than sent as null, so treat an absent key as
“not applicable to this node” rather than as a missing value. ledger_id, for
instance, appears on account nodes and not on category roots.
object
Stable identifier for an account, so the same account can be tracked across periods. Present on account nodes, absent on category roots.
Opaque — not a UUID, unlike the provider and business-entity ids. Treat it as a string and do not parse it.
Display name of the category or account.
Ledger type as classified in the chart of accounts — revenue or expense
on an income statement, asset, liability or equity on a balance sheet.
Reported for completeness; the node’s position in the statement is the
authoritative structure. Absent on the income statement’s derived categories,
which are neither.
Finer classification within a type, naming the category the account rolls up into. Present on account nodes.
Amount posted directly at this node, in cents. Often 0 on a root.
This node’s total in cents, including every descendant. This is the figure to read.
The account’s code in the chart of accounts, as a string. Ordering and reconciliation aid; not unique across entities.
The natural balance of the account. Accounting metadata.
This node’s total as a percentage of operating revenue, unrounded.
Computed for the five categories that hold accounts — operating revenues, cost of goods sold, operating expenses, other expenses, other income — and every node beneath them. Absent on the four derived categories (total net sales, gross profit, total operating profit, net profit).
Examples
One month-end position and the as-of snapshot, with per-account detail
GET .../financial_reports/balance_sheet/monthly?as_of_date=2026-08-31&months=2
The same envelope as monthly/summary with a balance_sheet key per column in
place of totals. This is the largest payload on this API; point a recurring job
at monthly/summary unless you need the accounts.
{ "provider_id": "9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f", "business_entity_id": "3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43", "accounting_basis": "CASH", "currency": "USD", "generated_at": "2026-09-02T09:14:33Z", "periods": [ { "label": "July 2026", "end_date": "2026-07-31", "is_closed": false, "is_complete": true, "balance_sheet": { "asset": { "record": { "name": "Asset", "type": "asset", "amount_cents": 0, "total_amount_cents": 39800000, "debit_credit": "debit", "children": [ { "name": "Bank Accounts", "type": "asset", "amount_cents": 0, "total_amount_cents": 17900000, "debit_credit": "debit", "children": [ { "ledger_id": "rhvm6QyfxbygB5warCZv8X", "name": "Operating Checking - 1234", "type": "asset", "sub_type": "bank_accounts", "amount_cents": 14700000, "total_amount_cents": 14700000, "sort_code": "1010", "debit_credit": "debit", "children": [] }, { "ledger_id": "kQ2p9TwmYxb4Ln7vRc3HdZ", "name": "Savings - 5678", "type": "asset", "sub_type": "bank_accounts", "amount_cents": 3200000, "total_amount_cents": 3200000, "sort_code": "1020", "debit_credit": "debit", "children": [] } ] }, { "ledger_id": "8FbNq1XjVpS6mKd0RyGtLa", "name": "Accounts Receivable", "type": "asset", "sub_type": "accounts_receivable", "amount_cents": 19000000, "total_amount_cents": 19000000, "sort_code": "1200", "debit_credit": "debit", "children": [] }, { "ledger_id": "3ZcHmR7yQvB1tXn5JsPwDf", "name": "Equipment, net", "type": "asset", "sub_type": "fixed_assets", "amount_cents": 2900000, "total_amount_cents": 2900000, "sort_code": "1500", "debit_credit": "debit", "children": [] } ] } }, "liability": { "record": { "name": "Liability", "type": "liability", "amount_cents": 0, "total_amount_cents": 12100000, "debit_credit": "credit", "children": [ { "ledger_id": "6WdKp2LmXc9BvT4nQzHyRs", "name": "Accounts Payable", "type": "liability", "sub_type": "accounts_payable", "amount_cents": 6950000, "total_amount_cents": 6950000, "sort_code": "2000", "debit_credit": "credit", "children": [] }, { "name": "Credit Cards", "type": "liability", "amount_cents": 0, "total_amount_cents": 1150000, "debit_credit": "credit", "children": [ { "ledger_id": "PmT5xR8kNc2WdY7bLq3ZvH", "name": "Business Card - 9012", "type": "liability", "sub_type": "credit_cards", "amount_cents": 1150000, "total_amount_cents": 1150000, "sort_code": "2100", "debit_credit": "credit", "children": [] } ] }, { "ledger_id": "Vn4Jc9QsX1mB6tKw2RyHpZ", "name": "Notes Payable", "type": "liability", "sub_type": "long_term_liabilities", "amount_cents": 4000000, "total_amount_cents": 4000000, "sort_code": "2400", "debit_credit": "credit", "children": [] } ] } }, "equity": { "record": { "name": "Equity", "type": "equity", "amount_cents": 0, "total_amount_cents": 27700000, "debit_credit": "credit", "children": [ { "ledger_id": "Lq7Bn3XvR9cM2kT5wZsHdP", "name": "Owner's Equity", "type": "equity", "sub_type": "equity", "amount_cents": 12000000, "total_amount_cents": 12000000, "sort_code": "3000", "debit_credit": "credit", "children": [] }, { "ledger_id": "Ty2Wm8KcQ4vN6xB1rZjHsL", "name": "Retained Earnings", "type": "equity", "sub_type": "equity", "amount_cents": 9420000, "total_amount_cents": 9420000, "sort_code": "3100", "debit_credit": "credit", "children": [] }, { "ledger_id": "Rc6Vx1NmT8bK3wQ5yZpHdJ", "name": "Net Income", "type": "equity", "sub_type": "equity", "amount_cents": 6280000, "total_amount_cents": 6280000, "sort_code": "3200", "debit_credit": "credit", "children": [] } ] } } } } ], "as_of": { "as_of_date": "2026-08-31", "is_closed": false, "balance_sheet": { "asset": { "record": { "name": "Asset", "type": "asset", "amount_cents": 0, "total_amount_cents": 41250000, "debit_credit": "debit", "children": [ { "name": "Bank Accounts", "type": "asset", "amount_cents": 0, "total_amount_cents": 18500000, "debit_credit": "debit", "children": [ { "ledger_id": "rhvm6QyfxbygB5warCZv8X", "name": "Operating Checking - 1234", "type": "asset", "sub_type": "bank_accounts", "amount_cents": 15200000, "total_amount_cents": 15200000, "sort_code": "1010", "debit_credit": "debit", "children": [] }, { "ledger_id": "kQ2p9TwmYxb4Ln7vRc3HdZ", "name": "Savings - 5678", "type": "asset", "sub_type": "bank_accounts", "amount_cents": 3300000, "total_amount_cents": 3300000, "sort_code": "1020", "debit_credit": "debit", "children": [] } ] }, { "ledger_id": "8FbNq1XjVpS6mKd0RyGtLa", "name": "Accounts Receivable", "type": "asset", "sub_type": "accounts_receivable", "amount_cents": 19750000, "total_amount_cents": 19750000, "sort_code": "1200", "debit_credit": "debit", "children": [] }, { "ledger_id": "3ZcHmR7yQvB1tXn5JsPwDf", "name": "Equipment, net", "type": "asset", "sub_type": "fixed_assets", "amount_cents": 3000000, "total_amount_cents": 3000000, "sort_code": "1500", "debit_credit": "debit", "children": [] } ] } }, "liability": { "record": { "name": "Liability", "type": "liability", "amount_cents": 0, "total_amount_cents": 12430000, "debit_credit": "credit", "children": [ { "ledger_id": "6WdKp2LmXc9BvT4nQzHyRs", "name": "Accounts Payable", "type": "liability", "sub_type": "accounts_payable", "amount_cents": 7180000, "total_amount_cents": 7180000, "sort_code": "2000", "debit_credit": "credit", "children": [] }, { "name": "Credit Cards", "type": "liability", "amount_cents": 0, "total_amount_cents": 1250000, "debit_credit": "credit", "children": [ { "ledger_id": "PmT5xR8kNc2WdY7bLq3ZvH", "name": "Business Card - 9012", "type": "liability", "sub_type": "credit_cards", "amount_cents": 1250000, "total_amount_cents": 1250000, "sort_code": "2100", "debit_credit": "credit", "children": [] } ] }, { "ledger_id": "Vn4Jc9QsX1mB6tKw2RyHpZ", "name": "Notes Payable", "type": "liability", "sub_type": "long_term_liabilities", "amount_cents": 4000000, "total_amount_cents": 4000000, "sort_code": "2400", "debit_credit": "credit", "children": [] } ] } }, "equity": { "record": { "name": "Equity", "type": "equity", "amount_cents": 0, "total_amount_cents": 28820000, "debit_credit": "credit", "children": [ { "ledger_id": "Lq7Bn3XvR9cM2kT5wZsHdP", "name": "Owner's Equity", "type": "equity", "sub_type": "equity", "amount_cents": 12000000, "total_amount_cents": 12000000, "sort_code": "3000", "debit_credit": "credit", "children": [] }, { "ledger_id": "Ty2Wm8KcQ4vN6xB1rZjHsL", "name": "Retained Earnings", "type": "equity", "sub_type": "equity", "amount_cents": 9420000, "total_amount_cents": 9420000, "sort_code": "3100", "debit_credit": "credit", "children": [] }, { "ledger_id": "Rc6Vx1NmT8bK3wQ5yZpHdJ", "name": "Net Income", "type": "equity", "sub_type": "equity", "amount_cents": 7400000, "total_amount_cents": 7400000, "sort_code": "3200", "debit_credit": "credit", "children": [] } ] } } } }}Malformed request — a missing or unparseable date, a path id that is not a UUID,
start_date after end_date, or a range that does not overlap the period this
entity has books for. Also returned when the request reached us over plaintext
HTTP; see INSECURE_TRANSPORT below and guides/authentication.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
Unparseable date
{ "error": { "code": "INVALID_REQUEST", "message": "start_date must be a valid date in YYYY-MM-DD format." }}Path id is not a UUID
{ "error": { "code": "INVALID_REQUEST", "message": "business_entity_id is not a valid UUID." }}Range sits entirely outside the reportable period
{ "error": { "code": "INVALID_REQUEST", "message": "The requested range does not overlap the period this entity has reportable books for. It must fall on or after books_start_date (see GET /business_entities) and must not be entirely in the future." }}Request sent over plaintext HTTP
{ "error": { "code": "INSECURE_TRANSPORT", "message": "This request was sent over plaintext HTTP, so any API key it carried was transmitted in the clear. Reissue it over HTTPS, and treat the key as compromised: rotate it." }}Missing, invalid, expired or revoked API key. One message covers every case on purpose — a caller cannot tell a revoked key from an unknown one.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
{ "error": { "code": "INVALID_API_KEY", "message": "Missing, invalid, expired or revoked API key." }}Your key is valid, but this call is not allowed. Either the operation is not served for your kind of key — the balance sheet and cash flow families are provider-only, eight operations in all — or your provider’s Flychain account is not active or not enrolled in the API programme. None of these is a credential problem; rotating the key will not help.
The partner scope refusals do not appear here: a partner key cannot reach these operations at all.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
A partner key on a provider-only operation
{ "error": { "code": "ENDPOINT_NOT_AVAILABLE", "message": "This endpoint is available to provider API keys only. See the reference at https://docs.flychain.us for the endpoints a partner key can read." }}Provider key whose Flychain account is not active
{ "error": { "code": "PROVIDER_NOT_ACTIVE", "message": "This provider's Flychain account is not active, so the API is not available to it. Contact Flychain." }}Provider key on an account not enrolled in the API programme
{ "error": { "code": "PROVIDER_API_NOT_ENABLED", "message": "This provider is not enrolled in the Flychain external API programme. Contact Flychain to request access." }}No provider or business entity exists with that id.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
{ "error": { "code": "PROVIDER_NOT_FOUND", "message": "No provider exists with that id." }}{ "error": { "code": "BUSINESS_ENTITY_NOT_FOUND", "message": "No business entity exists with that id." }}The entity exists and is in your relationship, but has no books a report can be
produced from — it is still onboarding, or it has been deactivated. It appears in
GET /business_entities with reporting_available: false; skip it rather than
recording a zero.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
{ "error": { "code": "BOOKS_NOT_AVAILABLE", "message": "This business entity does not currently have reportable books. GET /business_entities lists it with reporting_available: false." }}Our side. Safe to retry with backoff.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
{ "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Retry with backoff." }}We could not verify your API key right now — our identity provider was
unreachable or rate-limited. This is not an authentication failure: the key
may well be valid. Retry with backoff rather than treating it as a 401.
The failure shape for every error — validation, authorization, ours — so a client needs a single error path.
Match on code, not on message: the code set below is the contract and is
stable, while wording may be clarified. New codes may be added within v1 (see
guides/versioning), so treat an unrecognised code as “the HTTP status is
authoritative”.
This includes a request that never reaches a documented operation at all — an
unrouted path or a method we do not serve on that path, which is the failure you
are most likely to meet while integrating. Those are answered before any operation
runs, so no operation below lists them, but they arrive in this same shape, as
ENDPOINT_NOT_FOUND (404) and METHOD_NOT_ALLOWED (405). Either one means
check the URL rather than your credentials: the operations below are the whole
surface.
object
object
Machine-readable cause.
INVALID_REQUEST(400) — malformed dates, a non-UUID path id, an inverted range, or a range with no reportable books behind it.INSECURE_TRANSPORT(400) — the request was sent over plaintexthttp, so the key crossed the network in the clear. Rotate the key, then fix the URL; we refuse rather than redirect so this cannot pass unnoticed.INVALID_API_KEY(401) — missing, invalid, expired or revoked key.PARTNER_API_NOT_ENABLED(403) — your key is valid, but your organization is not enrolled in the API programme. Contact us; do not rotate the key.PROVIDER_NOT_ACTIVE(403) — a provider key whose Flychain account is not active. Contact us; do not rotate the key.PROVIDER_API_NOT_ENABLED(403) — a provider key on an account that is not enrolled in the API programme. Contact us; do not rotate the key.ENDPOINT_NOT_AVAILABLE(403) — the path exists and your key is valid, but that operation is not served for your kind of key. The balance sheet and cash flow families are provider-only. Your URL is not wrong; do not rotate the key.PROVIDER_NOT_IN_PARTNER_SCOPE(403) — the provider exists but is not in your relationship, including one that has left it.BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE(403) — the entity exists but does not belong to theprovider_idin the path.PROVIDER_NOT_FOUND(404) — no provider with that id.BUSINESS_ENTITY_NOT_FOUND(404) — no business entity with that id.ENDPOINT_NOT_FOUND(404) — the URL itself is not one we serve, as opposed to a record we do not have. Check the path against the operations below.METHOD_NOT_ALLOWED(405) — the path exists but not with that method; theAllowresponse header lists the ones it takes. Every operation here is aGET.BOOKS_NOT_AVAILABLE(409) — the entity has no reportable books.INTERNAL_ERROR(500) — ours; retry with backoff.AUTH_SERVICE_UNAVAILABLE(503) — we could not verify your key; retry with backoff, and do not treat it as an authentication failure.
Human-readable detail. Do not match on it.
Examples
{ "error": { "code": "AUTH_SERVICE_UNAVAILABLE", "message": "Unable to verify the API key right now. Retry with backoff." }}