Register a Business

Overview

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

Creates a business account tied to the applicant — the Fluz user whose token you submit with,
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,
Opens a KYB case for compliance review, and
Links the new business account to your application’s OAuth grant.

The mutation returns an accountId immediately, with a kybStatus of SUBMITTED.

This page is the parameter and error reference for the mutation itself. For prerequisites, the surrounding sequence of calls, and how to track a case to a decision, read Register & Verify Businesses first.

Required scopes

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token, account type `CONSUMER`
Required Scopes	`REGISTER_BUSINESS`

A business-account token is rejected by the schema before the mutation runs. Basic authentication is not accepted.

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. Max 255 characters
`dbaName`	`String`	No	The “Doing Business As” name. Max 255 characters
`businessStructure`	`BusinessStructure`	Yes	Must be one of: `LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `COOP`
`businessLegalAddress`	`BusinessLegalAddress`	Yes	The business legal address object (see below). Verified against an address-validation provider
`stateOfIncorporation`	`String`	Yes	The US state where the business is incorporated, as the full state name (e.g. `Delaware`)
`taxId`	`String`	Yes	Tax ID / EIN Number. Format: `XX-XXXXXXX` (2 digits, hyphen, 7 digits)
`authorizedSignerDocumentUrl`	`String`	Conditional	Required when the applicant owns less than 25% and is not the control person. Upload the document first
`soleProprietorshipDocumentUrl`	`String`	No	Optional supporting documentation for a sole proprietorship. No longer required for `SOLE_PROPRIETORSHIP`
`businessCategoryId`	`UUID`	Yes	Business category ID (from getBusinessCategories query)
`businessSubCategoryId`	`UUID`	Yes	Business sub-category ID (from getBusinessCategories query). Must belong to the supplied category
`natureOfBusiness`	`String`	No	Brief description of the nature of business. Strongly recommended — it speeds up manual review. Max 255 characters
`websiteUrl`	`String`	No	The business website URL. Strongly recommended for online sellers. Max 255 characters
`businessAccountUsage`	`[BusinessAccountUsage]`	Conditional	Array of usage types. Required if `businessAccountUsageOther` is not provided
`businessAccountUsageOther`	`String`	Conditional	Required if `businessAccountUsage` is empty or not provided. Max 255 characters
`externalReferenceId`	`String`	No	Your own identifier for this business. Stored on the business OAuth grant and returned on the `KYB_STATUS_UPDATE` webhook. Max 255 characters
`confirm`	`RegisterBusinessConfirm`	Yes	Beneficial-ownership certifications (see below)
`owners`	`[BusinessOwner]`	Yes	List of business owners. At least one required. Exactly one must be the applicant, and exactly one must be the control person

Address formattingFormat businessLegalAddress and each owner address using the structured fields below, with a real, deliverable address and a consistent city / state / postal code. Both may be international (country name, ISO 3166; some countries are restricted, e.g. Russia or Iran). The business legal address is additionally verified against an address-validation provider and rejected with BS-0002 if it cannot be confirmed; owner addresses receive field and state/province checks only. See Address Formatting Requirements.

BusinessLegalAddress

Field	Type	Required	Description
`streetAddressLine1`	`String`	Yes	Street address line 1. Max 255 characters
`streetAddressLine2`	`String`	No	Street address line 2
`city`	`String`	Yes	City
`state`	`String`	Yes	For the US, the state name (`New York`) or its two-letter code (`NY`). Elsewhere, the ISO 3166-2 subdivision name (`Ontario`)
`postalCode`	`String`	Yes	Postal code
`country`	`String`	Yes	Country name (ISO 3166). `US` is normalized to `United States`. Country codes are not accepted, and restricted countries are rejected

The stored address is the provider’s normalized version of what you sent, with city, state, and postalCode upper-cased — not the exact strings you submitted.

RegisterBusinessConfirm

Field	Type	Required	Set to `true` when
`allOwnersWith25PercentageOwnershipListed`	`Boolean`	Yes	At least one owner has `ownershipPercentage` of 25 or more
`noOwnersMoreThan25Percentage`	`Boolean`	Yes	No owner has `ownershipPercentage` of 25 or more

Both fields are non-nullable, so send both. Only the one matching your roster is enforced — set it to true and the other to false.

BusinessOwner

Field	Type	Required	Description
`firstName`	`String`	Yes	Owner’s first name
`lastName`	`String`	Yes	Owner’s last name
`emailAddress`	`String`	Conditional	At least one of `emailAddress` or `phoneNumber` is required. For the applicant, must match the email on their Fluz account
`phoneNumber`	`String`	Conditional	Must include a country calling code and be a real, dialable number (e.g. `+14155551234`)
`title`	`String`	Yes	Owner’s title in the company
`ownershipPercentage`	`Int`	Yes	Percentage of ownership (0–100). Total across all owners cannot exceed 100
`isControlPerson`	`Boolean`	Yes	Exactly one owner in the roster must be `true`
`isInvited`	`Boolean`	Yes	When `true`, Fluz emails the owner and they complete verification themselves. The applicant cannot be invited
`isUsPerson`	`Boolean`	Yes	Required on every owner. Selects the SSN path (`true`) or the document path (`false`)
`lastFourSsnDigits`	`String`	Conditional	Exactly 4 digits. Required when `isUsPerson` is `true` for owners who need full identity data. Omit for non-US persons
`dob`	`String`	Conditional	Date of birth as an ISO 8601 date (e.g. `1975-02-28`). Required for owners who need full identity data. Cannot be in the future; the owner must be at least 18
`address`	`OwnerAddress`	Conditional	Required for owners who need full identity data

isUsPerson is required on every owner. The GraphQL schema types it as a nullable Boolean, but validation rejects a missing or null value for all owners — including the applicant, invited owners, and owners below the beneficial-ownership threshold. The error reads owner N is invalid: isUsPerson is required.

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	For the US, the state name (`California`) or its two-letter code (`CA`). Elsewhere, the ISO 3166-2 subdivision name
`postalCode`	`String`	Yes	Postal code
`country`	`String`	Yes	Country name (ISO 3166). Restricted countries are rejected

BusinessStructure (enum)

Value	Notes
`LLC`	Single- or multi-member
`CORPORATION`	C-corp or S-corp
`PARTNERSHIP`	General or limited
`SOLE_PROPRIETORSHIP`	Exactly one owner, 100% ownership, who must be the control person
`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. Sending a value outside the enum 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 isControlPerson: true. Exactly one owner must carry that flag.
The applicant — the user your Bearer token belongs to — matched by emailAddress or phoneNumber. Exactly one owner must match, and that owner cannot be isInvited: true.

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.
Owner emails and phone numbers must be unique across the roster.
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.

Who needs full identity data

How much you send per owner depends on their role. Every owner needs the base fields; only some need identity data on top.

Owner role	Fields required
The applicant	Base fields only — their identity was verified before registration
Invited (`isInvited: true`)	Base fields only — they verify themselves after accepting
Owns under 25% and is not the control person	Base fields only
Owns 25% or more, or is the control person — and is neither the applicant nor invited	Base fields plus full identity data

Base fields: firstName, lastName, title, ownershipPercentage, isControlPerson, isInvited, isUsPerson, and at least one of emailAddress / phoneNumber. Full identity data: dob and address, plus lastFourSsnDigits when isUsPerson is true. When isUsPerson is false, omit lastFourSsnDigits — that owner completes document verification after registration via requestOwnerDocumentVerificationLink.

Validation quick reference

Most errors come down to formatting. Check these before submitting:

Field	Rule
`taxId`	`XX-XXXXXXX` — 2 digits, hyphen, 7 digits. Strip any other punctuation
`stateOfIncorporation`	Full US state name. A two-letter code is rejected here, even though address `state` allows one
`owners[].isUsPerson`	Required on every owner. `true` or `false`, never `null`
`owners[].dob`	ISO 8601 date, e.g. `1975-02-28`. Not in the future; owner at least 18
`owners[].phoneNumber`	Must include a country calling code and be a real number, e.g. `+14155551234`
`owners[].lastFourSsnDigits`	Exactly 4 digits, as a string. Only for `isUsPerson: true` owners needing full identity data
`owners[].ownershipPercentage`	Integer 0–100; sum across owners must not exceed 100
`owners[].isControlPerson`	Exactly one owner is `true`
`businessLegalAddress`	A real, deliverable address — it is checked against an address-validation provider
`businessLegalAddress.country`	ISO 3166 country name; restricted countries are rejected
`businessSubCategoryId`	Must belong to the supplied `businessCategoryId`; send both or neither
`businessAccountUsage` / `...UsageOther`	At least one of the two must be populated
`confirm`	Both booleans present; the one matching your roster set to `true`
Document URLs	Absolute `http`/`https` URLs, max 255 characters

Two formats changed from earlier versions of this API. Owner dob is now an ISO 8601 date (1975-02-28), not MM/DD/YYYY. Owner phoneNumber now requires a country calling code — a bare 10-digit US number is rejected. Note also that +15551234567 fails because 555 is not an assigned US area code; use a real area code in test data.

Documents

An authorized-signer document is required when the applicant is not a beneficial owner or control person, 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 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 — `SUBMITTED` on success
`success`	`Boolean`	Indicates whether the registration succeeded
`error`	`RegisterBusinessError`	Error information if registration failed

RegisterBusinessError

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

Validation and business-rule failures are returned inside the response payload, not as top-level GraphQL errors. Branch on the presence of error (or on success === false) rather than relying on the HTTP status.Permission failures are the exception: a wrong scope, a wrong account type, or Basic auth is rejected before the resolver runs and appears in the top-level errors array with data.registerBusiness set to null.

OAuth linkage can fail without failing the mutation. After the business is created and submitted, the API links the new business account to your application’s OAuth grant. If that step fails it is logged server-side only — the mutation still returns success: true with the accountId, but the business grant, and any externalReferenceId, may be missing. Contact support with the accountId rather than resubmitting; a retry is blocked by BS-0007.

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"],
        "externalReferenceId": "your-partner-user-id-123",
        "confirm": {
          "allOwnersWith25PercentageOwnershipListed": true,
          "noOwnersMoreThan25Percentage": false
        },
        "owners": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john@example.com",
            "phoneNumber": "+14155551234",
            "title": "Chief Executive Officer",
            "ownershipPercentage": 60,
            "isControlPerson": true,
            "isInvited": false,
            "isUsPerson": true
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "emailAddress": "jane@example.com",
            "phoneNumber": "+14155555678",
            "title": "Chief Financial Officer",
            "ownershipPercentage": 40,
            "isControlPerson": false,
            "isInvited": false,
            "isUsPerson": true,
            "lastFourSsnDigits": "5678",
            "dob": "1980-07-15",
            "address": {
              "streetAddressLine1": "789 Pine Street",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94104",
              "country": "United States"
            }
          }
        ]
      }
    }
  }'

John is the applicant and the control person, so he needs base fields only — his identity was verified before registration. Jane is a beneficial owner who is neither the applicant nor invited, so she needs full identity data.

Example Response

Success

{
  "data": {
    "registerBusiness": {
      "success": true,
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "SUBMITTED",
      "error": null
    }
  }
}

Error

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

Error Codes

Returned inside the payload, with success: false:

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, restricted, or failed address verification	Validate against Address Formatting Requirements. Check the postal code matches the city and state
`BS-0004`	InvalidBusinessAccountUsage	Selected business account usage is not allowed	Send only values from the `BusinessAccountUsage` enum, or describe the use 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	Category and sub-category are not valid or not properly connected	Re-fetch getBusinessCategories and pass a sub-category from the same category
`BS-0007`	RegistrationNotAllowed	The user already has an open application	Wait for approval or decline before resubmitting
`ARG-0001`	InvalidArguments	A field failed validation. The message names the field — owner roster problems, missing `isUsPerson`, an invalid phone number, ownership over 100%, a missing authorized-signer document, an underage or future `dob`, duplicate owner contacts, or an unverified applicant	Read `message` for the field name
`ARG-0002`	MissingArguments	A required field is missing	Read `message` for the field name
`AUTH-0008`	InvalidUserAccess	The applicant’s authorization is missing business scopes your application requires, or the `externalReferenceId` already belongs to another business	Have the user re-authorize, or use a unique reference
`AUTH-0025`	UnsuccessfulRegistration	Submission to KYB screening failed. The local records are rolled back	Resubmit the same application
`G-0001`	InternalError	Account provisioning or tax ID tokenization failed	Retry once. If it persists, contact support with the timestamp

Returned in the top-level errors array, with data.registerBusiness set to null:

Code	Name	Description
`AUTH-0002`	InvalidCredentials	Basic auth was used, or the token’s account type is not `CONSUMER`
`AUTH-0031`	InvalidScope	The token is missing the `REGISTER_BUSINESS` scope

Owner-roster problems are reported as ARG-0001, not BS-0003. BS-0003 (InvalidOwnerInformation) exists in the shared error catalogue but this API does not return it.

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 — the legal address goes through a real address-validation provider, so invented streets will fail.
EINs in staging must still satisfy the XX-XXXXXXX format, but do not need to correspond to a real entity.
Owner phone numbers must be possible numbers for their country. +15551234567 fails because 555 is not an assigned US area code; use a real area code with a 555 exchange, e.g. +14155551234.
Because a user cannot hold two open applications (BS-0007), test repeated registration paths with distinct test users.

Best practices

Validate client-side first. Nearly every error code is a formatting or selection problem you can catch before the network call. Doing so materially improves onboarding completion rates.
Expect one error at a time. Validation stops at the first problem it finds and the legal address is checked early, so a rejected submission may have more than one thing wrong with it.
Fetch categories at runtime. Never hardcode category UUIDs.
Send isUsPerson on every owner. It is the single most common cause of a rejected roster.
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

Either businessAccountUsage or businessAccountUsageOther must be provided.
Users cannot register a new business while they already have an ongoing application.
There is no idempotency key. Duplicate submissions are blocked by the open-application check instead.
Validation runs before anything is written, and the entity, application, charter, and address records are created in a single transaction — a rejected submission leaves nothing behind.
The taxId you submit is tokenized before storage and is never returned by any read operation.

KYB overview

Prerequisites, the end-to-end flow, and how to track a case to a decision.

Business categories

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

Submit business documents

Upload authorization documents and respond to KYB documentation requests.

Business KYB status

Read KYB status and per-owner verification progress after submitting.

Owner verification link

Generate an identity-verification link for owners on the document path.

Address formatting requirements

Rules that govern the legal and owner address objects.

​Overview

​Required scopes

​Basic mutation structure

​Parameters

​BusinessLegalAddress

​RegisterBusinessConfirm

​BusinessOwner

​OwnerAddress

​BusinessStructure (enum)

​BusinessAccountUsage (enum)

​Beneficial ownership requirements

​Who needs full identity data

​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

KYB overview

Business categories

Submit business documents

Business KYB status

Owner verification link

Address formatting requirements

Overview

Required scopes

Basic mutation structure

Parameters

BusinessLegalAddress

RegisterBusinessConfirm

BusinessOwner

OwnerAddress

BusinessStructure (enum)

BusinessAccountUsage (enum)

Beneficial ownership requirements

Who needs full identity data

Validation quick reference

Documents

Response details

RegisterBusinessError

cURL Example

Example Response

Success

Error

Error Codes

Testing in staging

Best practices

Notes

Related pages