> ## 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.
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).
## 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.
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.
## 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.
`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.
### 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 " \
-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
The status lifecycle and how to track a case to a decision.
Generate a link for owners reported as `DOCUMENTS` and `PENDING_CIP`.
The mutation that creates the account this query reads.