Skip to content
FlychainFlychainFlychain Docs

List the business entities your key can read

GET
/business_entities
curl --request GET \
  --url https://api.flychain.us/external/v1/business_entities \
  --header 'Authorization: Bearer <token>'

Partner and provider keys.

With a partner key: every business entity under the providers in your partner relationship.

With a provider key: every business entity under your own provider — including any that individual staff accounts in your organization are restricted from seeing in the Flychain dashboard, because a key belongs to the organization rather than to a person. See guides/authentication.

Either way, records are ordered by provider then entity legal name, and each carries its parent provider_id, so the two ids together address every report endpoint.

Read reporting_available before pulling a report. An entity exists on Flychain before its books are live, so an entity mid-onboarding is listed with reporting_available: false and must be skipped rather than treated as a business with zero revenue. Requesting a report for one returns 409 BOOKS_NOT_AVAILABLE.

Read books_start_date too. It is the earliest date the entity’s books cover, and requested ranges are clamped to it — a trailing-twelve-month request against an entity whose books begin three months ago returns three months, not nine empty ones. See guides/data-semantics.

Every key is always present, null where the underlying value is unset. A stable key set is easier to parse, and an absent key would be indistinguishable from a field we stopped returning.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The business entities your key can read.

Media typeapplication/json
object
business_entities
required
Array<object>

A legal entity whose books we keep. This is the level financial reports are produced at, and the business_entity_id here is what every report path takes.

object
provider_id
required

The parent provider. Both ids together address every report.

string format: uuid
business_entity_id
required

Stable for the life of the account.

string format: uuid
provider_legal_name
required

The parent provider’s legal name, so an entity is identifiable without a second call. null only in the rare case where the provider became unreadable between the two reads behind this list.

string | null
legal_name
required

The entity’s registered legal name.

string
dba
required

Trading name, where it differs from the legal name.

string | null
ein
required

The entity’s federal EIN, unformatted digits. The identifier to reconcile against your own records, since books are kept per legal entity.

null where we do not hold it yet — an entity can exist on Flychain before its EIN is recorded — so treat absence as “unknown”, not as “no EIN”.

string | null
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
reporting_available
required

Whether this entity has books a report can be produced from right now.

false in both directions: an entity still onboarding, and one that has been deactivated. Skip these rather than recording a zero — a report request returns 409 BOOKS_NOT_AVAILABLE.

This is the field that stops a mid-onboarding business reading as a business with no revenue.

boolean
books_start_date
required

The earliest date this entity’s books cover, YYYY-MM-DD.

Requested ranges are clamped to it, and the clamp is echoed back as the effective range on every report. A trailing-twelve-month request against an entity whose books begin three months ago returns three months of data — that is “books start here”, not nine months of zero revenue. A range entirely before this date is a 400, never an empty statement.

null where the entity has no books yet (reporting_available: false).

string | null format: date
books_closed_through
required

The most recent date a Flychain bookkeeper has finalized the books through, YYYY-MM-DD. Figures on or before this date are settled; figures after it are provisional and may still be revised.

This is the value behind the is_closed flag on every report. null where no month has been closed yet.

string | null format: date
key
additional properties
any
key
additional properties
any
Examples

One reportable entity and one still onboarding

{
  "business_entities": [
    {
      "provider_id": "9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f",
      "business_entity_id": "3f5d8b16-7c94-42a1-b0e6-58d9c2a71b43",
      "provider_legal_name": "Riverbend Pediatric Therapy LLC",
      "legal_name": "Riverbend Pediatric Therapy LLC",
      "dba": "Riverbend Therapy — Northside",
      "ein": "123456789",
      "accounting_basis": "CASH",
      "reporting_available": true,
      "books_start_date": "2026-05-01",
      "books_closed_through": "2026-06-30"
    },
    {
      "provider_id": "7b2d4f60-5a18-4c37-90ab-1e6f8d0c5a24",
      "business_entity_id": "c48a1e93-2d76-4b05-8f31-9a7c6e2b4d18",
      "provider_legal_name": "Northstar Care Group LLC",
      "legal_name": "Northstar Care Group LLC",
      "dba": null,
      "ein": null,
      "accounting_basis": null,
      "reporting_available": false,
      "books_start_date": null,
      "books_closed_through": null
    }
  ]
}

400

Section titled “400”

The request reached us over plaintext http:// rather than https://, so any API key in its Authorization header crossed the network unencrypted.

We refuse rather than redirect: a redirect cannot un-send the credential, and answering 301 would teach your client that the insecure URL works. Rotate the key — see 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
ExampleinsecureTransport

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."
  }
}

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: your organization is not enrolled in the API programme, or — for a provider key — its Flychain account is not active. Deliberately not a 401: the credential is fine and rotating it will not help. Contact us.

No scope refusal is possible on this endpoint: it takes no provider or business-entity id, so there is nothing that could be outside your key’s reach.

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

Your organization is not enrolled in the API programme

{
  "error": {
    "code": "PARTNER_API_NOT_ENABLED",
    "message": "This partner is not enrolled in the Flychain external API programme. Contact Flychain to request access."
  }
}

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."
  }
}