> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Register & Verify Businesses
> Create a business account programmatically, submit beneficial ownership information, and take the account through KYB verification.
## Overview
The **registerBusiness** mutation creates a business account on the Fluz platform. In a single call it:
1. Creates a business account tied to an existing Fluz user (the primary owner),
2. Stores the legal entity record — legal name, structure, tax ID, state of incorporation, legal address, category, and intended use of the account,
3. Stores the beneficial ownership information for each owner you supply, and
4. 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
```mermaid theme={null}
sequenceDiagram
autonumber
participant App as Your Application
participant API as Fluz GraphQL API
participant Files as Fluz File Upload (REST)
participant KYB as Fluz Compliance / KYB
Note over App,API: Step 0 — the primary owner must exist as a Fluz user
App->>API: registerUser (only if the primary owner is new)
API-->>App: success
Note over App,API: Step 1 — resolve category IDs
App->>API: query getBusinessCategories
API-->>App: businessCategoryId + businessSubCategoryId values
opt businessStructure = SOLE_PROPRIETORSHIP
App->>Files: Upload document
Files-->>App: document URL
end
Note over App,API: Step 2 — submit the business
App->>API: mutation registerBusiness(input)
alt Validation fails
API-->>App: success false, with error code and message
App->>App: Correct the field and resubmit
else Validation passes
API-->>App: accountId plus kybStatus PENDING
API->>KYB: Open KYB case
end
Note over KYB,App: Step 3 — asynchronous review
KYB->>KYB: Entity, tax ID, address, and owner checks
KYB-->>API: Decision (or request for more documentation)
App->>API: Check business account status
API-->>App: Updated KYB status
Note over App,API: Step 4 — go live
App->>API: Create spend accounts and issue cards
```
### Step-by-step
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](/user-registration).
Fluz recommends the primary owner complete [identity verification (KYC)](/docs/user-kyc-verification) before or alongside the business submission, since owner identity data is reviewed as part of KYB.
Both the app-level grant and the individual user grant must be active. See [Application Scopes](/fluz-dashboard/application-scopes).
Call [getBusinessCategories](/business-categories) 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`.
Only required when `businessStructure` is `SOLE_PROPRIETORSHIP`. Upload the document first, then pass the returned URL in `soleProprietorshipDocumentUrl`. See [Submit business documents](/submit-business-documents).
Send the full entity record and every owner in one call. Handle the response as described in [Response details](#response-details) — errors are returned inside the payload, not as GraphQL errors.
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
```mermaid theme={null}
stateDiagram-v2
[*] --> PENDING: registerBusiness returns accountId
PENDING --> PENDING: Additional documentation requested
PENDING --> APPROVED: Entity and ownership checks cleared
PENDING --> DECLINED: Checks not cleared
APPROVED --> [*]: Business can transact
DECLINED --> [*]: New submission required
```
| 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`:
```graphql theme={null}
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
```graphql theme={null}
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](/submit-business-documents) 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 formatting**
Format `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](/concepts/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](/user-registration) 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:
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
```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-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
```json theme={null}
{
"data": {
"registerBusiness": {
"accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"kybStatus": "PENDING"
}
}
}
```
### Error
```json theme={null}
{
"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](/concepts/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](/business-categories) 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](/docs/staging-vs-live-environment).
* Use [Test Addresses](/docs/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.
## Related pages
Upload sole proprietorship documents and respond to KYB documentation requests.
Fetch the category and sub-category IDs required by this mutation.
Create the Fluz user who will act as primary owner.
Rules that govern the legal and owner address objects.