List the business entities your key can read

GET

/business_entities

const url = 'https://api.flychain.us/external/v1/business_entities';
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/business_entities \
  --header 'Authorization: Bearer <token>'

Every business entity under the providers in your partner relationship, ordered by provider then entity legal name. Each record carries its parent provider_id, and 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

PartnerApiKey

Responses

200

The business entities in your partner relationship.

application/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

reportableAndOnboarding

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
    }
  ]
}

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.

application/json

The failure shape for every error raised inside a documented operation — 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”.

One exception, and it is the one you are most likely to meet while integrating. A request that does not reach a documented operation at all — an unrouted path (404) or a method this API does not serve (405) — is rejected before this layer, and its body may be a different shape or not JSON at all. Treat the HTTP status as authoritative there, and check the URL: 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.
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_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.
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 INVALID_API_KEY PARTNER_API_NOT_ENABLED PROVIDER_NOT_IN_PARTNER_SCOPE BUSINESS_ENTITY_NOT_IN_PARTNER_SCOPE PROVIDER_NOT_FOUND BUSINESS_ENTITY_NOT_FOUND 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

invalidKey

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing, invalid, expired or revoked API key."
  }
}

403

Your key is valid, but your organization is not enrolled in the API programme. Deliberately not a 401: the credential is fine and rotating it will not help. Contact us to be enrolled.

application/json

The failure shape for every error raised inside a documented operation — validation, authorization, ours — so a client needs a single error path.

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.
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_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.
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

message

required

Human-readable detail. Do not match on it.

string

key

additional properties

any

key

additional properties

any

Examples

notEnrolled

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

500

Our side. Safe to retry with backoff.

application/json

The failure shape for every error raised inside a documented operation — validation, authorization, ours — so a client needs a single error path.

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.
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_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.
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

message

required

Human-readable detail. Do not match on it.

string

key

additional properties

any

key

additional properties

any

Examples

internalError

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Retry with backoff."
  }
}

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.

application/json

The failure shape for every error raised inside a documented operation — validation, authorization, ours — so a client needs a single error path.

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.
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_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.
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

message

required

Human-readable detail. Do not match on it.

string

key

additional properties

any

key

additional properties

any

Examples

authUnavailable

{
  "error": {
    "code": "AUTH_SERVICE_UNAVAILABLE",
    "message": "Unable to verify the API key right now. Retry with backoff."
  }
}