Skip to content
FlychainFlychainFlychain Docs

Cash flow totals for a date range

GET
/provider/{provider_id}/business_entity/{business_entity_id}/financial_reports/cash_flow_report/summary
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/cash_flow_report/summary?start_date=2026-07-01&end_date=2026-07-31' \
  --header 'Authorization: Bearer <token>'

Provider keys only. A partner key is refused with 403 ENDPOINT_NOT_AVAILABLE.

The report totals for one range and nothing else — the endpoint to integrate against if you store a fixed set of figures per period.

Five integers. Three are flows over the range (total_inflow_cents, total_outflow_cents, net_cash_flow_cents) and two are positions at its endpoints (starting_cash_balance_cents, ending_cash_balance_cents). That mix is the thing to build around: the flows of two adjacent ranges add up, the balances do not.

The start_date / end_date in the response are the effective range we reported on after clamping, not necessarily the range you asked for.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
provider_id
required
string format: uuid

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-6a8b5c4d3e2f
business_entity_id
required
string format: uuid

The business entity, from GET /business_entities. Must belong to the provider_id in the same path.

Example
3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43

Query Parameters

Section titled “Query Parameters”
start_date
required
string format: date
/^\d{4}-\d{2}-\d{2}$/

First day of the requested range, inclusive.

Must be a real calendar date, zero-padded, in YYYY-MM-DD form — 2026-7-1 and 2026-02-31 are both 400 INVALID_REQUEST. Ranges are evaluated in UTC.

Raised to the entity’s books_start_date when it falls earlier. If the whole requested range sits before the books begin, the result is 400 INVALID_REQUEST rather than a zero statement, so a range with no books behind it can never read as a period with no revenue.

Example
2026-07-01
end_date
required
string format: date
/^\d{4}-\d{2}-\d{2}$/

Last day of the requested range, inclusive. Same format rules as start_date, and must not be earlier than it.

Capped at today when it falls in the future, which is the ordinary case for a job that asks for the current month every day. The response echoes the effective range it used.

Example
2026-07-31

Responses

Section titled “Responses”

200

Section titled “200”

The report totals for the effective range.

Media typeapplication/json

The range envelope carrying the report totals.

object
provider_id
required
string format: uuid
business_entity_id
required
string format: uuid
start_date
required

First day of the effective range, inclusive — what we reported on after clamping, not necessarily what was requested.

string format: date
end_date
required

Last day of the effective range, inclusive. Compare both dates against what you asked for: a difference means the range was clamped to the entity’s books or to today.

string format: date
accounting_basis
required

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.

string | null
Allowed values: CASH ACCRUAL
currency
required

Currency of every amount in the payload. Always USD — the key exists so it never has to be assumed.

string
Allowed values: USD
is_closed
required

Whether the books are finalized through end_date (that is, end_date is on or before the entity’s books_closed_through).

false means the figures are provisional and may still be revised as transactions are reconciled. This is the flag to trust, rather than inferring from the calendar — see guides/data-semantics.

boolean
generated_at
required

When this payload was produced, ISO 8601 UTC. Reports are computed on request, so this is also the as-of time of the figures.

string format: date-time
totals
required

The five figures a cash flow report carries besides its ledgers, every one a signed integer in cents.

Three are flows over the range and three are related by net_cash_flow_cents = total_inflow_cents + total_outflow_cents — outflows are already negative, so they sum rather than subtract. Two are positions at the range’s endpoints. The distinction matters when you combine periods: the flows of two adjacent ranges add up, the balances do not.

object
total_inflow_cents
required

Cash in over the range. Positive.

integer
total_outflow_cents
required

Cash out over the range, as a negative number — or 0 where nothing left in the range. Unlike the income statement’s expense categories, which are positive magnitudes, outflows here carry their sign so that inflow plus outflow is the net.

integer
starting_cash_balance_cents
required

Cash on hand at the start of the effective range. A position, not a flow — do not sum it across periods.

integer
ending_cash_balance_cents
required

Cash on hand at the end of the effective range. Equal to starting_cash_balance_cents + net_cash_flow_cents.

integer
net_cash_flow_cents
required

total_inflow_cents + total_outflow_cents. Negative where the entity spent more than it took in over the range.

integer
key
additional properties
any
Examples
ExamplejulyCashFlowTotals

July 2026 cash flow totals for one entity

GET /provider/9c1e7a42-.../business_entity/3f5d8b16-.../financial_reports/cash_flow_report/summary?start_date=2026-07-01&end_date=2026-07-31

is_closed: false because this entity’s books are closed through 2026-06-30, so July’s figures are still provisional.

The three flows relate: 4167000 + -2730000 = 1437000. The two balances bracket them: 8450000 + 1437000 = 9887000.

{
  "provider_id": "9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f",
  "business_entity_id": "3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43",
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "accounting_basis": "CASH",
  "currency": "USD",
  "is_closed": false,
  "generated_at": "2026-08-20T14:02:11Z",
  "totals": {
    "total_inflow_cents": 4167000,
    "total_outflow_cents": -2730000,
    "starting_cash_balance_cents": 8450000,
    "ending_cash_balance_cents": 9887000,
    "net_cash_flow_cents": 1437000
  }
}

400

Section titled “400”

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.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples

Unparseable date

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "start_date must be a valid date in YYYY-MM-DD format."
  }
}

401

Section titled “401”

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.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples
ExampleinvalidKey
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing, invalid, expired or revoked API key."
  }
}

403

Section titled “403”

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.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
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."
  }
}

404

Section titled “404”

No provider or business entity exists with that id.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples
{
  "error": {
    "code": "PROVIDER_NOT_FOUND",
    "message": "No provider exists with that id."
  }
}

409

Section titled “409”

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.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples
ExamplenoBooks
{
  "error": {
    "code": "BOOKS_NOT_AVAILABLE",
    "message": "This business entity does not currently have reportable books. GET /business_entities lists it with reporting_available: false."
  }
}

500

Section titled “500”

Our side. Safe to retry with backoff.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples
ExampleinternalError
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Retry with backoff."
  }
}

503

Section titled “503”

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.

Media typeapplication/json

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
error
required
object
code
required

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 plaintext http, 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 the provider_id in 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; the Allow response header lists the ones it takes. Every operation here is a GET.
  • 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.
string
Allowed values: INVALID_REQUEST INSECURE_TRANSPORT INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_ACTIVE PROVIDER_API_NOT_ENABLED ENDPOINT_NOT_AVAILABLE PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND ENDPOINT_NOT_FOUND METHOD_NOT_ALLOWED BOOKS_NOT_AVAILABLE INTERNAL_ERROR AUTH_SERVICE_UNAVAILABLE
message
required

Human-readable detail. Do not match on it.

string
key
additional properties
any
key
additional properties
any
Examples
ExampleauthUnavailable
{
  "error": {
    "code": "AUTH_SERVICE_UNAVAILABLE",
    "message": "Unable to verify the API key right now. Retry with backoff."
  }
}