KYB Testing

Use these values to drive registerBusiness to a predictable outcome in staging, and to get each owner to READY.

Staging only. These values only work on https://transactional-graph.staging.fluzapp.com/api/v1/graphql. Never submit a real business’s tax ID or owner details to staging.

Before you start, you’ll need:

an OAuth Integration application that Fluz has moved to ACTIVE, with the REGISTER_BUSINESS scope on its Permissions list and a non-empty Business permissions list (see Prepare Your Accounts and Business Accounts in OAuth);
an applicant user who has completed the OAuth grant for that application (see Client-Facing OAuth Grant Flow);
that applicant’s KYC returned APPROVED through the SSN path (see Test KYC Flows);
a CONSUMER token for that applicant, minted with their personal accountId (see How accounts work).

The order of operations

Every staging KYB test follows the same sequence. Most errors in staging come from running a step early or with the wrong token.

Create the applicant with registerUser (leave out deferSeatAssignment), or use an existing staging user.
Send the applicant through OAuth. In staging, no SMS is sent: enter 123456 as the sign-in code. If the account picker appears, choose Apply for a business account.
Verify the applicant with verifyUserInformation and the approved test identity, using a CONSUMER token.
Register the business with registerBusiness, still using the CONSUMER token.
Switch to a BUSINESS token (same userId, the new business accountId) and track owners and kybStatus with getBusiness.

Known issue — applicants created with registerUser. Some of these users are missing an OAuth setting, so registerBusiness fails with AUTH-0008 (“does not have permission to access the application”) even after a valid grant. Until the fix ships, send the user through /authorize once, choose Apply for a business account, and reuse the same external_id as their existing grant. If it still fails, contact your Fluz contact with the user ID.

Test tax IDs

Pass these as taxId on registerBusiness, in the format XX-XXXXXXX. The tax ID is the only field that decides the staging outcome.

`taxId`	Outcome
`11-1111111`	Approved
`22-2222222`	Declined
`33-3333333`	Declined

Any other value goes to review and isn’t guaranteed to resolve in staging.

Test legal address

The business legal address is checked against an address-validation provider, even in staging. Invented streets fail with BS-0002. Use a value from Test Addresses.

Example: an auto-approved business

Call with the applicant’s CONSUMER token. Get businessCategoryId and businessSubCategoryId from getBusinessCategories (also CONSUMER); never hardcode them.

mutation RegisterBusiness($input: RegisterBusinessInput!) {
  registerBusiness(input: $input) {
    accountId
    kybStatus
    success
    error { code message }
  }
}

{
  "input": {
    "businessName": "Test Approved LLC",
    "dbaName": "Test Approved",
    "businessStructure": "LLC",
    "businessLegalAddress": {
      "streetAddressLine1": "<FROM_TEST_ADDRESSES>",
      "city": "<FROM_TEST_ADDRESSES>",
      "state": "<FROM_TEST_ADDRESSES>",
      "postalCode": "<FROM_TEST_ADDRESSES>",
      "country": "United States"
    },
    "stateOfIncorporation": "Delaware",
    "taxId": "11-1111111",
    "businessCategoryId": "<FROM_getBusinessCategories>",
    "businessSubCategoryId": "<FROM_getBusinessCategories>",
    "natureOfBusiness": "Integration testing",
    "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN"],
    "externalReferenceId": "test-business-001",
    "confirm": {
      "allOwnersWith25PercentageOwnershipListed": true,
      "noOwnersMoreThan25Percentage": false
    },
    "owners": [
      {
        "firstName": "John",
        "lastName": "Smith",
        "emailAddress": "<APPLICANT_EMAIL>",
        "phoneNumber": "<APPLICANT_PHONE>",
        "title": "Chief Executive Officer",
        "ownershipPercentage": 100,
        "isControlPerson": true,
        "isInvited": false,
        "isUsPerson": true
      }
    ]
  }
}

Use the RegisterBusinessInput field names shown here: businessName, taxId, businessStructure. The applicant owner’s email or phone must match the user the token belongs to. Every business needs one control person; beneficial owners are only required for anyone holding 25% or more.

A success response returns an accountId and kybStatus: SUBMITTED. Store the accountId: you need it to mint the BUSINESS token for everything that follows. The applicant’s existing grant extends to the new business account, so generateUserAccessToken works for it while KYB is still pending.

Getting owners to `READY`

Mint a BUSINESS token (the same userId plus the new business accountId) and call getBusiness. Each owner has a verificationType:

`verificationType`	How to complete it in staging
`SSN`	The owner verifies as themselves: a token for the owner’s own user, calling `verifyUserInformation` with an approved test identity. See Test KYC Flows
`DOCUMENTS`	Call `requestOwnerDocumentVerificationLink` with the `BUSINESS` token and complete the hosted flow

requestOwnerDocumentVerificationLink returns ARG-0001 for SSN owners. It only works for DOCUMENTS owners.

kybStatus: APPROVED is about the business. Each owner is tracked separately, so an owner can still read PENDING_CIP after the business is approved. Treat the business as ready only when kybStatus is final and every owner reports READY.

Common staging errors

Error	Where you see it	Cause	Fix
`AUTH-0030 … current status: PERSONAL`	Any call	The application was made with Create new app and isn’t an active OAuth Integration application	Use an OAuth Integration application that Fluz has activated
`AUTH-0031`	`generateUserAccessToken`, `getAccountsByUserId`	The applicant hasn’t completed the OAuth grant	Run step 2 of the order of operations
`AUTH-0008` “Invalid user access”	`generateUserAccessToken`	The applicant was registered with `deferSeatAssignment: true`	Register a new applicant without the flag
`AUTH-0002` “requires account type CONSUMER”	`getBusinessCategories`, `registerBusiness`	Called with a `BUSINESS` token	Use the applicant’s `CONSUMER` token
`AUTH-0008` “does not have permission to access the application”	`registerBusiness`	Known issue for applicants created with `registerUser`	See the known-issue note above
`ARG-0001`	`registerBusiness`	The applicant has no successful KYC on file	Verify the applicant first
`ARG-0001`	`requestOwnerDocumentVerificationLink`	The owner’s `verificationType` is `SSN`	Verify that owner with `verifyUserInformation` instead
Owner stuck at `PENDING_CIP`, `provided: false`	`getBusiness`	The owner (often the applicant) has no SSN verification on file	Run `verifyUserInformation` for that owner with the approved test identity
`BS-0002`	`registerBusiness`	The legal address failed validation	Use a value from Test Addresses
`BS-0007`	`registerBusiness`	The applicant already has an application in flight	Use a fresh applicant

Changing a business after approval

There is no API to change a business’s legal name, address, or owners once it’s registered. Contact Fluz support for those changes.

Resetting

There is no API to reset a business’s KYB outcome, or to cancel an in-flight application. A successful submission blocks the same applicant from registering again (BS-0007) until it resolves. To test repeatedly, use a fresh applicant user, or ask your Fluz contact to reset one.

Get started

Fluz Dashboard

Quickstarts

KYB Testing

The order of operations

Test tax IDs

Test legal address

Example: an auto-approved business

Getting owners to `READY`

Common staging errors

Changing a business after approval

Resetting

Next steps

Register & Verify Businesses

Onboard & Verify a Business

​The order of operations

​Test tax IDs

​Test legal address

​Example: an auto-approved business

​Getting owners to READY

​Common staging errors

​Changing a business after approval

​Resetting

​Next steps

Register & Verify Businesses

Onboard & Verify a Business

The order of operations

Test tax IDs

Test legal address

Example: an auto-approved business

Getting owners to `READY`

Common staging errors

Changing a business after approval

Resetting

Next steps