Register & Verify Businesses

Overview

The registerBusiness mutation creates a business account on the Fluz platform. In a single call it:

Creates a business account tied to an existing Fluz user (the primary owner),
Stores the legal entity record — legal name, structure, tax ID, state of incorporation, legal address, category, and intended use of the account,
Stores the beneficial ownership information for each owner you supply, and
Opens a KYB (Know Your Business) case for compliance review.

The mutation returns an accountId immediately, along with a kybStatus of PENDING. Registration succeeding means Fluz accepted and validated your submission — it does not mean the business has been approved. Approval happens asynchronously once the KYB review completes.

Registration is validation, not approval. A success response with kybStatus: PENDING confirms the payload passed field-level validation and a KYB case was opened. Build your integration so it waits for an approved status before attempting to fund the account or issue cards.

What a business account unlocks

Once KYB is approved, the business account can be used for the commercial side of the platform:

Business spend accounts and balances
Commercial virtual cards, including bulk issuance
Authorized users and card-level spend controls
Approval workflows for cards, transfers, and reimbursements
Business-level transaction reporting and expense annotation

When to use this endpoint

Use registerBusiness when your platform onboards businesses on Fluz rails and you want to collect entity and ownership data in your own UI rather than sending users into a Fluz-hosted flow. If you would rather Fluz host the collection and document upload experience, talk to your account manager about the widget-based onboarding option instead.

Registration flow

End-to-end sequence

Step-by-step

Make sure the primary owner is a registered Fluz user

At least one owner in the owners array — the primary owner — must already exist as a Fluz user, and the emailAddress you send for that owner must match the email on their Fluz account exactly. If the person does not have an account yet, create one first with registerUser.Fluz recommends the primary owner complete identity verification (KYC) before or alongside the business submission, since owner identity data is reviewed as part of KYB.

Confirm your application holds the REGISTER_BUSINESS scope

Both the app-level grant and the individual user grant must be active. See Application Scopes.

Resolve the business category and sub-category

Call getBusinessCategories and let the user pick a category and one of that category’s sub-categories. Do not hardcode these UUIDs — they can change, and a sub-category from a different category will be rejected with BS-0006.

Upload a sole proprietorship document, if applicable

Only required when businessStructure is SOLE_PROPRIETORSHIP. Upload the document first, then pass the returned URL in soleProprietorshipDocumentUrl. See Submit business documents.

Submit the registerBusiness mutation

Send the full entity record and every owner in one call. Handle the response as described in Response details — errors are returned inside the payload, not as GraphQL errors.

Wait for the KYB decision, then provision

The account is created in PENDING. Surface that state to your user rather than implying they are live. Once the status moves to approved, create spend accounts and issue cards.

KYB status lifecycle

Status	What it means	What your app should do
`PENDING`	The submission was accepted and is under review.	Show an “under review” state. Do not attempt to fund the account or issue cards.
`APPROVED`	KYB cleared. The business account is usable.	Provision spend accounts, issue cards, and unlock your business UI.
`DECLINED`	KYB did not clear.	Surface a neutral message and direct the user to support. Do not auto-retry the submission.

Checking status after registration

There is no KYB webhook event today, so your integration should read the status when the user returns to your business onboarding screen, and on a low-frequency background schedule (for example, hourly — not per page load). You can confirm the business account exists and identify it against the user with getAccountsByUserId:

query GetAccountsByUserId($userId: UUID!) {
  getAccountsByUserId(userId: $userId) {
    accountId
    type
    accountName
  }
}

Reviews are typically resolved within one to two business days, but can take longer when additional documentation is requested. If a case appears stalled, contact your account manager with the accountId rather than resubmitting — a second submission will be blocked by BS-0007.

Required scopes

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token
Required Scopes	`REGISTER_BUSINESS`

Basic mutation structure

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

Parameters

Parameter	Type	Required	Description
`businessName`	`String`	Yes	The legal business name, exactly as it appears on the entity’s formation documents and tax filings
`dbaName`	`String`	No	The “Doing Business As” name
`businessStructure`	`BusinessStructure`	Yes	Must be one of: `LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `COOP`
`businessLegalAddress`	`BusinessLegalAddress`	Yes	The business legal address object (see below)
`stateOfIncorporation`	`String`	Yes	The state where the business is incorporated
`taxId`	`String`	Yes	Tax ID / EIN Number. Format: `XX-XXXXXXX` (2 digits, hyphen, 7 digits)
`soleProprietorshipDocumentUrl`	`String`	Conditional	Required if `businessStructure` is `SOLE_PROPRIETORSHIP`. Upload the document first
`businessCategoryId`	`UUID`	Yes	Business category ID (from getBusinessCategories query)
`businessSubCategoryId`	`UUID`	Yes	Business sub-category ID (from getBusinessCategories query)
`natureOfBusiness`	`String`	No	Brief description of the nature of business. Strongly recommended — it speeds up manual review
`websiteUrl`	`String`	No	The business website URL. Strongly recommended for online sellers
`businessAccountUsage`	`[BusinessAccountUsage]`	Conditional	Array of usage types. Required if `businessAccountUsageOther` is not provided
`businessAccountUsageOther`	`String`	Conditional	Required if `businessAccountUsage` is empty or not provided
`owners`	`[BusinessOwner]`	Yes	List of business owners. At least one owner required. Primary owner must be a registered Fluz user

Address formattingFormat businessLegalAddress and each owner address using the structured fields below, with a real, deliverable address and a consistent city / state / postal code. The business legal address may be international (country name, ISO 3166; some countries are restricted, e.g. Russia or Iran). Owner addresses must be US-based. A malformed or mismatched address returns BS-0002 (business legal address) or BS-0003 (owner information). See Address Formatting Requirements for details.

BusinessLegalAddress

Field	Type	Required	Description
`streetAddressLine1`	`String`	Yes	Street address line 1
`streetAddressLine2`	`String`	No	Street address line 2
`city`	`String`	Yes	City
`state`	`String`	Yes	State/province
`postalCode`	`String`	Yes	Postal code
`country`	`String`	Yes	Country name (ISO 3166). Some countries are restricted for KYB registration, e.g. Russia or Iran

BusinessOwner

Field	Type	Required	Description
`firstName`	`String`	Yes	Owner’s first name
`lastName`	`String`	Yes	Owner’s last name
`emailAddress`	`String`	Yes	Owner’s email. Ensure you use the email address the user registered with on the Fluz platform.
`title`	`String`	Yes	Owner’s title in the company
`ownershipPercentage`	`Int`	Yes	Percentage of ownership (0-100). Total ownership across all owners cannot exceed 100
`lastFourSsnDigits`	`String`	Yes	Last 4 digits of SSN
`dob`	`String`	Yes	Date of birth in `MM/DD/YYYY` format (e.g., `02/28/1975`)
`phoneNumber`	`String`	Yes	Phone number: minimum 10 digits, digits only
`address`	`OwnerAddress`	Yes	Owner’s address (must be US-based, see `OwnerAddress`)

OwnerAddress

Field	Type	Required	Description
`streetAddressLine1`	`String`	Yes	Street address line 1
`streetAddressLine2`	`String`	No	Street address line 2
`city`	`String`	Yes	City
`state`	`String`	Yes	Must be a valid US state name (e.g., `California`, `New York`, `Texas`)
`postalCode`	`String`	Yes	Must be 5 digits for US ZIP code format

BusinessStructure (enum)

Value	Notes
`LLC`	Single- or multi-member
`CORPORATION`	C-corp or S-corp
`PARTNERSHIP`	General or limited
`SOLE_PROPRIETORSHIP`	Requires `soleProprietorshipDocumentUrl`
`COOP`	Cooperative

Any structure not on this list is rejected with BS-0005. Trusts, non-profits, and other entity types are handled case by case — contact your account manager before building against them.

BusinessAccountUsage (enum)

Value	Use for
`CORPORATE_GIFTING`	Buying gift cards for employees, clients, or incentive programs
`CORPORATE_SPENDING_ADMIN`	Managing employee cards and controlled spend
`REWARDS_MAXIMIZER`	Optimizing rewards on business spend
`GIFT_CARD_RESELLING`	Reselling gift cards
`PURCHASE_GOODS_FOR_BUSINESS_USE`	General procurement of goods and services
`ONLINE_SELLER_RETAIL_PURCHASING`	Sourcing inventory for online retail

Send every value that applies. If none fit, omit businessAccountUsage and describe the intended use in businessAccountUsageOther. Selecting a usage type your application is not approved for returns BS-0004.

Beneficial ownership requirements

KYB review depends on getting the ownership picture right the first time. Collect and submit:

Every individual who owns 25% or more of the entity, directly or indirectly.
A control person — an individual with significant responsibility for managing the entity (CEO, CFO, managing member, general partner, or similar) — even if they hold no equity. Send them with an ownershipPercentage of 0 and an accurate title.
At least one owner who is a registered Fluz user, with a matching emailAddress.

Practical notes:

Total ownershipPercentage across the array must not exceed 100, but it does not need to equal 100. If a business is 40/35/25 across three individuals plus a non-owner CEO, submit all four with percentages of 40, 35, 25, and 0.
Where an entity (rather than a person) holds equity, look through to the individuals behind it and submit those individuals.
title is a free-text field, but it is read by a human reviewer. Use recognizable titles (“Chief Executive Officer”, “Managing Member”) rather than internal shorthand.

Validation quick reference

Most BS-000x errors come down to formatting. Check these before submitting:

Field	Rule
`taxId`	`XX-XXXXXXX` — 2 digits, hyphen, 7 digits. Strip any other punctuation.
`owners[].dob`	`MM/DD/YYYY`
`owners[].phoneNumber`	Digits only, minimum 10. No `+`, spaces, parentheses, or hyphens.
`owners[].lastFourSsnDigits`	Exactly 4 digits, as a string
`owners[].ownershipPercentage`	Integer 0–100; sum across owners ≤ 100
`owners[].address.state`	Full US state name, not the two-letter abbreviation
`owners[].address.postalCode`	5 digits
`businessLegalAddress.country`	ISO 3166 country name; restricted countries are rejected
`businessSubCategoryId`	Must belong to the supplied `businessCategoryId`
`businessAccountUsage` / `...UsageOther`	Exactly one of the two must be populated
`soleProprietorshipDocumentUrl`	Required when `businessStructure` is `SOLE_PROPRIETORSHIP`

Date format differs from user registration. registerBusiness expects owner dates of birth as MM/DD/YYYY, while registerUser expects YYYY-MM-DD. Reusing one formatter across both calls is a common source of BS-0003.

Documents

Sole proprietorships must upload supporting documentation before registering, and any structure may be asked for additional documentation during KYB review. Both paths are covered on one page:

Submit business documents

Upload endpoint, accepted sole proprietorship documents, and what to do when compliance requests more information.

Response details

Field	Type	Description
`accountId`	`UUID`	The account ID of the newly created business
`kybStatus`	`String`	The KYB status of the business (initially `PENDING`)
`success`	`Boolean`	Indicates if the registration was successful (on error)
`error`	`RegisterBusinessError`	Error information if registration failed (on error)

RegisterBusinessError

Field	Type	Description
`message`	`String`	Brief informational error message
`code`	`String`	Predefined code listed in the table below

Failures are returned inside the response payload, not as top-level GraphQL errors. Always branch on the presence of error (or on success === false) rather than relying on the HTTP status or a GraphQL errors array.

cURL Example

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RegisterBusiness($input: RegisterBusinessInput!) { registerBusiness(input: $input) { accountId kybStatus success error { message code } } }",
    "variables": {
      "input": {
        "businessName": "Acme Corporation",
        "dbaName": "Acme Co",
        "businessStructure": "LLC",
        "businessLegalAddress": {
          "streetAddressLine1": "123 Main Street",
          "streetAddressLine2": "Suite 100",
          "city": "San Francisco",
          "state": "California",
          "postalCode": "94102",
          "country": "United States"
        },
        "stateOfIncorporation": "California",
        "taxId": "12-3456789",
        "businessCategoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "businessSubCategoryId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "natureOfBusiness": "E-commerce retail",
        "websiteUrl": "https://acme.example.com",
        "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN", "PURCHASE_GOODS_FOR_BUSINESS_USE"],
        "owners": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john@example.com",
            "title": "CEO",
            "ownershipPercentage": 60,
            "lastFourSsnDigits": "1234",
            "dob": "02/28/1975",
            "phoneNumber": "4155551234",
            "address": {
              "streetAddressLine1": "456 Oak Avenue",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94103"
            }
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "emailAddress": "jane@example.com",
            "title": "CFO",
            "ownershipPercentage": 40,
            "lastFourSsnDigits": "5678",
            "dob": "07/15/1980",
            "phoneNumber": "4155555678",
            "address": {
              "streetAddressLine1": "789 Pine Street",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94104"
            }
          }
        ]
      }
    }
  }'

Example Response

Success

{
  "data": {
    "registerBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING"
    }
  }
}

Error

{
  "data": {
    "registerBusiness": {
      "success": false,
      "error": {
        "message": "The entered tax id taxId must be in format XX-XXXXXXX (2 digits, hyphen, 7 digits)",
        "code": "BS-0001"
      }
    }
  }
}

Error Codes

Code	Name	Description	How to resolve
`BS-0001`	InvalidTaxId	The tax ID must be in format `XX-XXXXXXX` (2 digits, hyphen, 7 digits)	Reformat the EIN. Strip spaces and any punctuation other than the single hyphen.
`BS-0002`	InvalidBusinessLegalAddress	Business legal address is incorrect	Validate against Address Formatting Requirements.
`BS-0003`	InvalidOwnerInformation	One or more owner information is incorrect	Check `dob` format, digits-only `phoneNumber`, 4-digit SSN, full state name, and 5-digit ZIP.
`BS-0004`	InvalidBusinessAccountUsage	Selected business account usage is not allowed	Confirm your app is approved for that usage type, or describe it in `businessAccountUsageOther`.
`BS-0005`	InvalidBusinessStructure	Selected business structure is not allowed	Use one of the five supported enum values, or contact your account manager for other entity types.
`BS-0006`	InvalidBusinessCategory	Ensure that business category and business subcategory are valid and properly connected (subcategories from different categories cannot be combined; for example, Art cannot be selected with a Pharmacy subcategory)	Re-fetch getBusinessCategories and pass a sub-category from the same category.
`BS-0007`	RegistrationNotAllowed	Wait until the last business finishes registration before starting a new one	The user has an open application. Wait for approval or decline before resubmitting.
`AR-0001`	MissingArguments	Required argument is missing (see error message for details)	Read `message` for the field name.
`AR-0002`	InvalidArguments	Invalid argument provided (see error message for details)	Read `message` for the field name.
`AU-0001`	UnsuccessfulRegistration	General registration failure	Retry once. If it persists, contact support with the request payload and timestamp.

Testing in staging

Register against the staging GraphQL endpoint shown in the examples above. See Staging vs. Live Environment.
Use Test Addresses for addresses that pass validation deterministically.
EINs in staging must still satisfy the XX-XXXXXXX format, but do not need to correspond to a real entity.
Because a user cannot hold two open applications (BS-0007), test repeated registration paths with distinct test users.

Best practices

Validate client-side first. Every BS-000x code except BS-0007 is a formatting or selection problem you can catch before the network call. Doing so materially improves onboarding completion rates.
Fetch categories at runtime. Never hardcode category UUIDs.
Do not auto-retry on a declined KYB. Resubmission will not change the outcome and creates duplicate cases.
Store the accountId immediately. It is your only handle on the application and the reference support will ask for.
Communicate the pending state honestly. Tell the user their business is under review and roughly how long it takes, rather than dropping them into a business dashboard that cannot yet transact.
Collect ownership completely the first time. Missing beneficial owners is the most common cause of a review stalling for additional documentation.

Notes

When specifying account usage, either businessAccountUsage or businessAccountUsageOther must be provided.
Users cannot register a new business if they already have an ongoing application. They must wait for the current application to be approved or rejected before submitting another one.

Submit business documents

Upload sole proprietorship documents and respond to KYB documentation requests.

Business categories

Fetch the category and sub-category IDs required by this mutation.

Register customers

Create the Fluz user who will act as primary owner.

Address formatting requirements

Rules that govern the legal and owner address objects.

​Overview

​What a business account unlocks

​When to use this endpoint

​Registration flow

​End-to-end sequence

​Step-by-step

​KYB status lifecycle

​Checking status after registration

​Required scopes

​Basic mutation structure

​Parameters

​BusinessLegalAddress

​BusinessOwner

​OwnerAddress

​BusinessStructure (enum)

​BusinessAccountUsage (enum)

​Beneficial ownership requirements

​Validation quick reference

​Documents

Submit business documents

​Response details

​RegisterBusinessError

​cURL Example

​Example Response

​Success

​Error

​Error Codes

​Testing in staging

​Best practices

​Notes

​Related pages

Submit business documents

Business categories

Register customers

Address formatting requirements

Overview

What a business account unlocks

When to use this endpoint

Registration flow

End-to-end sequence

Step-by-step

KYB status lifecycle

Checking status after registration

Required scopes

Basic mutation structure

Parameters

BusinessLegalAddress

BusinessOwner

OwnerAddress

BusinessStructure (enum)

BusinessAccountUsage (enum)

Beneficial ownership requirements

Validation quick reference

Documents

Response details

RegisterBusinessError

cURL Example

Example Response

Success

Error

Error Codes

Testing in staging

Best practices

Notes

Related pages