List the providers your key can read

GET

/providers

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

• Production

Partner and provider keys.

With a partner key: every provider in your partner relationship, ordered by legal_name. A provider that leaves the relationship stops appearing here — see guides/data-semantics on telling “gone” apart from “never existed”.

With a provider key: a one-element list holding your own provider record. This is how an integration learns the provider_id that every report path takes, so it is normally the first call you make and the only time you need this endpoint. It returns a list rather than a bare object so that one client can parse either audience’s response.

Reports are addressed per business entity, so GET /business_entities is the endpoint an integration polls thereafter.

Authorizations

• PartnerApiKey
• ProviderApiKey

Responses

200

The providers your key can read.

Media typeapplication/json

object

providers

required

Array<object>

A provider: the business as a client of Flychain. Reports are addressed per business entity, not per provider.

object

provider_id

required

Stable for the life of the account. Used in the report paths.

string format: uuid

legal_name

required

Registered legal name.

string

dba

required

Trading name, where it differs from the legal name.

string | null

other_names

required

Any additional names this business is known by. Often empty.

Array<string>

tax_id

required

Provider-level tax identifier, unformatted digits.

For matching a provider against your own records. Note that books — and therefore every report — are kept per legal entity, so the entity-level ein is usually the field to reconcile on.

string | null

key

additional properties

any

key

additional properties

any

Examples

Two providers in one partner relationship

{
  "providers": [
    {
      "provider_id": "9c1e7a42-0b3d-4e58-9f21-6a8b5c4d3e2f",
      "legal_name": "Riverbend Pediatric Therapy LLC",
      "dba": "Riverbend Therapy — Northside",
      "other_names": [],
      "tax_id": "123456789"
    },
    {
      "provider_id": "7b2d4f60-5a18-4c37-90ab-1e6f8d0c5a24",
      "legal_name": "Northstar Care Group LLC",
      "dba": null,
      "other_names": [
        "Northstar Care"
      ],
      "tax_id": "987654321"
    }
  ]
}

A provider key reading its own record

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

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

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

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

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

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

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