Business KYB Status

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:

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.

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

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
`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 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
`READY`	The owner’s verification requirement is satisfied	Nothing
`FAILED`	Present in the schema for forward compatibility; not currently returned	—

cURL Example

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

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

KYB overview

The status lifecycle and how to track a case to a decision.

Owner verification link

Generate a link for owners reported as DOCUMENTS and PENDING_CIP.

Register a business

The mutation that creates the account this query reads.

​Overview

​Required scopes

​Basic query structure

​Response details

​BusinessOwnerStatus

​ExternalKybStatus (enum)

​BusinessOwnerVerificationType (enum)

​ExternalBusinessOwnerStatus (enum)

​cURL Example

​Example Response

​Error Codes

​Best practices

​Related pages

KYB overview

Owner verification link

Register a business

Overview

Required scopes

Basic query structure

Response details

BusinessOwnerStatus

ExternalKybStatus (enum)

BusinessOwnerVerificationType (enum)

ExternalBusinessOwnerStatus (enum)

cURL Example

Example Response

Error Codes

Best practices

Related pages