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

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.They’re redirected back to your redirect_uri with ?code=...&state=.... Validate state, then capture the single-use code server-side.

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.

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.

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.Three things that reject most first attempts:

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

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:

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

Owners on the document path get a link from requestOwnerDocumentVerificationLink; owners you marked isInvited: true are emailed by Fluz and verify themselves. Keep going until kybStatus is final and every owner reports READY.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. 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.

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

The full flow

You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

Onboard & connect a customer

​The full flow

​You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

Onboard & connect a customer

The full flow

You’re done 🎉