Onboard & verify a business

This Quickstart is Onboard & Connect a Customer for businesses. You’ll configure an application that can only ever land on a business account, walk an owner through the OAuth grant, register their legal entity and beneficial ownership roster, track the KYB case to a decision, and prove the connection by issuing a card on the business account. The person in front of you is always an individual first. They sign in as themselves, they get identity-verified as themselves, and then they register a business. Everything below follows that order.

Prerequisites

A Fluz account with a staging application — see Prepare your accounts and API credentials. It must be an OAuth Integration application that Fluz has moved to ACTIVE; apps made with Create new app fail with AUTH-0030.
A client_id, client_secret, and registered redirect_uri — see Configure OAuth App.
Requests go to the sandbox — no real money, no real PII. See Staging vs. Live Environment.

Which token, when

Two tokens appear in this flow, and using the wrong one is the most common cause of a failed first run.

Steps	Token	Minted with
KYC, `getBusinessCategories`, `registerBusiness`	`CONSUMER` — the applicant’s personal account	The applicant’s `userId` and personal `accountId`
`getBusiness`, owner verification links, everything after approval	`BUSINESS`	The same `userId` and the new business `accountId`

The full flow

Configure the application for businesses

Two permission lists live on the Permissions tab of your app, and they are edited independently.

List	What to put on it
Permissions	What your app may do on a personal account. Include the permission to register a business — it is granted by the personal account, so it belongs here and nowhere else.
Business permissions	What your app may do on a business account once one exists.

A non-empty Business permissions list is what makes your app business-enabled. Leave it empty and users are never offered the option to apply for a business account, no matter what else you configure.While you’re in the app editor, register your redirect_uri on the OAuth tab and add a webhook URL subscribed to KYB status update — that’s how you’ll learn the review finished without polling.

The consent screen is built from these lists, not from your authorize URL. A permission you don’t select here is never offered to the user and can never appear on a token. Full detail: Business Accounts in OAuth.

Ask Fluz to restrict the app to business accounts

Fluz can configure your application so the flow never settles on a personal account. With that in place, a user who has no business account skips the account picker entirely and goes straight into business registration.

This isn’t self-serve. Contact your Fluz account manager to have the restriction applied to your application. Until it is, users with no business account are offered their personal account alongside the option to apply for a business one — and some of them will pick the personal account.

Skip this if your app legitimately serves both consumers and businesses. Asking for it is a statement that a personal-account grant is always a bug for you.

Send the owner through the OAuth grant

Build the authorize URL:

Authorization URL

    https://uni.staging.fluzapp.com/authorize
      ?response_type=code
      &client_id=<YOUR_OAUTH_CLIENT_ID>
      &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
      &state=<UNGUESSABLE_VALUE_YOU_STORED>
      &external_id=<YOUR_ID_FOR_THIS_ACCOUNT>

With the app restricted to business accounts, a first-time user sees: sign-in and 2FA, then a consent screen carrying two groups — the consumer permissions they’re granting now, and the business permissions being pre-approved for the business they’re about to create. The list is read-only; they accept all of it or they don’t finish. If the app isn’t restricted, the user picks Apply for a business account on the account picker.They’re redirected back to your redirect_uri with ?code=...&state=.... Validate state, then capture the single-use code server-side.

Did you create this owner with registerUser? Registration doesn’t authorize your app, so this step is still required. These users have no password and sign in with a one-time code sent by SMS to the registered phone — authenticator apps can’t complete it. In staging, no SMS is sent: enter 123456.Known issue: some users created with registerUser are missing an OAuth setting, so registerBusiness later fails with AUTH-0008. Until the fix ships, make sure this pass through /authorize chooses Apply for a business account and reuses the same external_id as the user’s existing grant.

Give the business its own external_id, derived from your own business record — not from the owning user. An external ID binds to one Fluz account on first use, so an ID you spend on someone’s personal account can’t be reused for their business.

Full parameter reference: Client-Facing OAuth Grant Flow.

Exchange the code for the applicant's token

Same exchange as any other grant — Basic auth with base64 of client_id:client_secret:

Exchange (cURL)

    curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=<AUTH_CODE>&redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>" \
      -H "Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>"

The redirect_uri must byte-match the one you used at /authorize.

The business doesn’t exist yet, so this token belongs to the applicant’s personal account — that is correct, and it’s the token registerBusiness requires. Read the account off the exchange response and persist it rather than inferring it from your own records of who started the flow.

This consent is what lets the applicant register a business. A CONSUMER token from generateUserAccessToken works for registerBusiness only after it, and only when you mint it with the same externalReferenceId as the external_id above. See Applicant authorization.

Verify the applicant's identity (KYC)

KYB verifies the business and the other owners. It does not verify the applicant, so the applicant has to be verified before you register anything — otherwise registration fails with ARG-0001.Call verifyUserInformation with the applicant’s token. In staging this test identity always returns APPROVED:

    mutation VerifyUserInformation(
      $firstName: String!
      $lastName: String!
      $streetLine1: String!
      $city: String!
      $state: String!
      $postalCode: String!
      $country: String!
      $dateOfBirth: String!
      $ssnLast4: String!
    ) {
      verifyUserInformation(
        firstName: $firstName
        lastName: $lastName
        streetLine1: $streetLine1
        city: $city
        state: $state
        postalCode: $postalCode
        country: $country
        dateOfBirth: $dateOfBirth
        ssnLast4: $ssnLast4
      ) {
        status
        message
      }
    }

    {
      "firstName": "John",
      "lastName": "Smith",
      "streetLine1": "222333 Peachtree Place",
      "city": "Atlanta",
      "state": "GA",
      "postalCode": "30318",
      "country": "United States",
      "dateOfBirth": "02/28/1975",
      "ssnLast4": "3333"
    }

Which check the applicant needs depends on the isUsPerson value you’ll send for them in the next step: true requires a successful SSN (CIP) verification on file, false requires a successful document verification. See User KYC Verification and Testing KYC Flows.

A user can be submitted at most 3 times before returning ERROR. Don’t burn attempts on the user you’re about to make an applicant. An ERROR reading User is already KYC verified doesn’t count as an attempt.

If the applicant’s owner record later shows PENDING_CIP with verificationType: SSN and provided: false, they were isUsPerson: true without a successful SSN verification on file. Run this step for them with the SSN path.

First resolve the category the entity trades under — never hardcode these UUIDs:

    query {
      getBusinessCategories {
        id
        name
        subCategories { id name }
      }
    }

Then submit the entity and the full ownership roster in one call, still with the applicant’s personal-account token:

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

    {
      "input": {
        "businessName": "Acme Corporation",
        "dbaName": "Acme Co",
        "businessStructure": "LLC",
        "businessLegalAddress": {
          "streetAddressLine1": "123 Main Street",
          "city": "San Francisco",
          "state": "California",
          "postalCode": "94102",
          "country": "United States"
        },
        "stateOfIncorporation": "California",
        "taxId": "12-3456789",
        "businessCategoryId": "<FROM_getBusinessCategories>",
        "businessSubCategoryId": "<FROM_getBusinessCategories>",
        "natureOfBusiness": "E-commerce retail",
        "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN"],
        "externalReferenceId": "your-business-id-123",
        "confirm": {
          "allOwnersWith25PercentageOwnershipListed": true,
          "noOwnersMoreThan25Percentage": false
        },
        "owners": [
          {
            "firstName": "John",
            "lastName": "Smith",
            "emailAddress": "john@example.com",
            "phoneNumber": "+14155551234",
            "title": "Chief Executive Officer",
            "ownershipPercentage": 100,
            "isControlPerson": true,
            "isInvited": false,
            "isUsPerson": true
          }
        ]
      }
    }

A success response returns an accountId and a kybStatus of SUBMITTED. Store the accountId immediately — it’s your only handle on the application.Four things that reject most first attempts:

The wrong token. getBusinessCategories and registerBusiness both need the applicant’s CONSUMER token. A BUSINESS token fails with AUTH-0002 (“requires account type CONSUMER”).
isUsPerson is required on every owner, including the applicant and invited owners. It’s the single most common cause of a rejected roster.
Exactly one owner must be the applicant — matched by email or phone against the token’s user — and exactly one must be the control person. Beneficial owners are only required for anyone holding 25% or more.
The legal address is checked against an address-validation provider. Invented streets fail with BS-0002; use Test Addresses.

Errors come back inside the response payload, not as GraphQL errors — branch on success and the error object. Full parameter and error reference: Register a Business. Staging tax IDs that force an outcome: KYB Testing.

Get the remaining owners verified, then wait

SUBMITTED means the payload validated and a case opened. It does not mean approved.Mint a business-account token — generateUserAccessToken with the applicant’s userId and the new business accountId — and read the roster. The applicant’s grant extends to the new business automatically, so this works while KYB is still pending.

    query GetBusiness {
      getBusiness {
        accountId
        kybStatus
        owners { id name verificationType status }
      }
    }

Owners on the document path get a link from requestOwnerDocumentVerificationLink; owners on the SSN path verify as themselves with verifyUserInformation (the link returns ARG-0001 for them). Owners you marked isInvited: true are emailed by Fluz and verify themselves. Keep going until kybStatus is final and every owner reports READY — an approved business can still have an owner at PENDING_CIP.The status moves PENDING → APPROVED or DECLINED, usually within one to two business days. Take the decision off the KYB status update webhook you configured in Step 1 and use getBusiness for reconciliation — hourly, not per page load.

Show the user an honest “under review” state. Don’t drop them into a business dashboard that can’t transact yet, and don’t auto-retry a decline — a second submission is blocked by BS-0007. There’s no API to change the business’s legal name, address, or owners after submission; those changes go through Fluz support. Full lifecycle: Register & Verify Businesses.

Operate on the business account — prove it

Once kybStatus is APPROVED, run any Fluz operation with the business-account token and it executes against the business. There is no separate business API.

    mutation {
      createVirtualCard(
        input: {
          idempotencyKey: "9f2c4d61-77aa-4b0e-8f2a-1c9d3e5b7a04"
          offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
          spendLimit: 250.00
          lockCardNextUse: true
          cardNickname: "First card on a verified business"
        }
      ) {
        virtualCardId
        virtualCardLast4
        status
      }
    }

An ACTIVE card back means the loop is closed: configured → authorized → verified → registered → approved → operating.

You’re done 🎉

You’ve taken a business from an empty application to a verified account that can spend. From here:

Business accounts in OAuth

The two permission lists, the account picker, and which account a code resolves to.

Register & verify businesses

Prerequisites, the KYB status lifecycle, and tracking a case to a decision.

Submit business documents

Authorized-signer uploads and responding to documentation requests.

KYB testing

Staging tax IDs, owner verification, and the errors you’ll hit along the way.

Onboard & connect a customer

The same journey for individuals.

Want to learn more? Contact us at support@fluz.app to speak with our experts or request a demo.

Get started

Fluz dashboard

Quickstarts

Onboard & verify a business

Which token, when

The full flow

You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

KYB testing

Onboard & connect a customer

​Which token, when

​The full flow

​You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

KYB testing

Onboard & connect a customer

Which token, when

The full flow

You’re done 🎉