Skip to content
FlychainFlychainFlychain Docs

List the providers your key can read

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

Every provider in your partner relationship, ordered by legal_name.

Reports are addressed per business entity, so GET /business_entities is the endpoint an integration normally polls. This one is here for the provider-level list on its own.

A provider that leaves the relationship stops appearing here. See guides/data-semantics on telling “gone” apart from “never existed”.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The providers in your partner relationship.

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
ExampletwoProviders

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

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 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
ExampleinvalidKey
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing, invalid, expired or revoked API key."
  }
}

403

Section titled “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.

Media typeapplication/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
ExamplenotEnrolled
{
  "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 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
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 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
ExampleauthUnavailable
{
  "error": {
    "code": "AUTH_SERVICE_UNAVAILABLE",
    "message": "Unable to verify the API key right now. Retry with backoff."
  }
}