> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Business KYB status

> Read a business account's KYB status and each owner's identity-verification progress with the getBusiness query.

## Overview

The **getBusiness** query returns the current KYB status for a business account, together with a snapshot of the ownership roster and where each owner stands in identity verification.

It is how you answer two different questions after [registering a business](/business-registration):

* **Is the business approved yet?** Read `kybStatus`.
* **What is holding it up?** Read `owners` — an owner still on `PENDING_CIP` or `PENDING_INVITE` is usually the answer.

<Note>
  You can also receive status changes by subscribing to the `KYB_STATUS_UPDATE` webhook, which avoids scheduled reads. The webhook carries the business status only, so call this query when you need the owner roster. See [Tracking an application](/kyb-overview#tracking-an-application).
</Note>

## Required scopes

| Property | Value |
| - | - |
| Endpoint | GraphQL API |
| Authentication | OAuth Bearer Token, account type `BUSINESS` |
| Required Scopes | `REGISTER_BUSINESS` |

The query takes no arguments — it always resolves the business tied to the calling token's `accountId`. Use a token minted for the business account that `registerBusiness` returned; the consumer token you registered with will not work.

<Info>
  When Fluz creates the business OAuth grant during registration, `REGISTER_BUSINESS` is force-included in that grant's scopes, so a token minted for the new business account can always call this query.
</Info>

## Basic query structure

```graphql theme={null}
query GetBusiness {
  getBusiness {
    accountId
    kybStatus
    owners {
      id
      name
      verificationType
      status
    }
  }
}
```

## Response details

| Field | Type | Description |
| - | - | - |
| `accountId` | `UUID` | The business account this response describes |
| `kybStatus` | `ExternalKybStatus` | `PENDING`, `APPROVED`, or `DECLINED` |
| `owners` | `[BusinessOwnerStatus]` | Current roster snapshot, including owners added or updated after registration |

### BusinessOwnerStatus

| Field | Type | Description |
| - | - | - |
| `id` | `UUID` | The owner's identity ID, or `null` for invited owners who have not accepted yet. See [Which IDs can be used](#which-ids-can-be-used) |
| `name` | `String` | Display name derived from the linked identity record |
| `verificationType` | `BusinessOwnerVerificationType` | What identity verification is *expected* for this owner |
| `status` | `ExternalBusinessOwnerStatus` | The owner's current verification progress |

### ExternalKybStatus (enum)

| Value | What it means | What your app should do |
| - | - | - |
| `PENDING` | The case is under review, awaiting screening results, or waiting on an owner to verify | Keep tracking. Do not fund the account or issue cards |
| `APPROVED` | KYB cleared | Provision spend accounts and issue cards |
| `DECLINED` | KYB did not clear | Surface a neutral message and direct the user to support. Do not auto-retry |

`registerBusiness` returns `SUBMITTED`, which is not a value of this enum — that same moment reads as `PENDING` here.

<Warning>
  `PENDING` collapses several internal states into one value. That matters in one place: [requestOwnerDocumentVerificationLink](/owner-verification-link) only works while the case is in one specific internal state, and `kybStatus` cannot tell you which one you are in.
</Warning>

### BusinessOwnerVerificationType (enum)

| Value | When you see it |
| - | - |
| `SSN` | The owner verifies via SSN (CIP) — they were submitted with `isUsPerson: true` |
| `DOCUMENTS` | The owner verifies by uploading identity documents — they were submitted with `isUsPerson: false` |
| `NOT_REQUIRED` | No additional verification is expected: a provided owner who owns under 25% and is not the control person |

### ExternalBusinessOwnerStatus (enum)

| Value | What it means | What your app should do |
| - | - | - |
| `PENDING_INVITE` | The owner has an outstanding invite and has not accepted yet | Nothing. Fluz emails them; there is no API to resend or accept |
| `PENDING_CIP` | The owner still needs the expected identity verification | For `DOCUMENTS` owners, [send them a verification link](/owner-verification-link) |
| `READY` | The owner's verification requirement is satisfied | Nothing |
| `FAILED` | Present in the schema for forward compatibility; not currently returned | — |

## cURL Example

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "query GetBusiness { getBusiness { accountId kybStatus owners { id name verificationType status } } }"
  }'
```

## Example Response

```json theme={null}
{
  "data": {
    "getBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING",
      "owners": [
        {
          "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
          "name": "John Doe",
          "verificationType": "SSN",
          "status": "READY"
        },
        {
          "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "name": "Jane Smith",
          "verificationType": "DOCUMENTS",
          "status": "PENDING_CIP"
        },
        {
          "id": null,
          "name": "Carol Investor",
          "verificationType": "SSN",
          "status": "PENDING_INVITE"
        }
      ]
    }
  }
}
```

Jane needs a [verification link](/owner-verification-link). Carol was invited and will be emailed by Fluz. The business cannot be approved until both reach `READY`.

## Error Codes

This query returns all failures in the top-level `errors` array — there is no `success: false` payload.

| Code | Name | Description | How to resolve |
| - | - | - | - |
| `AUTH-0002` | InvalidCredentials | Basic auth was used; the token's account type is not `BUSINESS`; the token is missing `userId` or `accountId`; or no business exists for that `accountId` | Use a token minted for the business `accountId` that `registerBusiness` returned |
| `AUTH-0031` | InvalidScope | The token is missing the `REGISTER_BUSINESS` scope | Add the scope and re-mint the token |
| `G-0001` | InternalError | Internal error | Retry once. If it persists, contact support with the `accountId` |

## Best practices

* **Prefer the webhook, read for reconciliation.** Subscribe to `KYB_STATUS_UPDATE` for latency, and read this query when the user returns to your onboarding screen or on a low-frequency background schedule — hourly, not per page load.
* **Wait for both signals before going live.** `kybStatus: APPROVED` and every owner at `READY`.
* **Do not treat a link request as progress.** An owner's `status` changes when they actually complete verification, not when you generate their link.

## Related pages

<CardGroup cols={2}>
  <Card title="KYB overview" href="/kyb-overview">
    The status lifecycle and how to track a case to a decision.
  </Card>

  <Card title="Owner verification link" href="/owner-verification-link">
    Generate a link for owners reported as `DOCUMENTS` and `PENDING_CIP`.
  </Card>

  <Card title="Register a business" href="/business-registration">
    The mutation that creates the account this query reads.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.