> ## 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 Customers Overview

> Bring individuals and businesses onto Fluz over the API — the two onboarding tracks, the order operations have to happen in, and what each verification outcome means.

Before anyone can hold value or move money on Fluz, two things have to be true: an account exists, and the identity behind it has been verified. This section covers doing both programmatically.

There are two tracks — individuals and businesses — and a business track always contains an individual one.

<CardGroup cols={2}>
  <Card title="Individuals (KYC)" icon="user">
    `registerUser` creates the account. `verifyUserInformation` verifies the person. Verification is synchronous, with a hard limit on attempts.
  </Card>

  <Card title="Businesses (KYB)" icon="building-2">
    `registerBusiness` creates the entity and starts verification. The result is asynchronous — the account opens in `PENDING` and resolves later.
  </Card>
</CardGroup>

<Warning>
  **Both are restricted.** User registration requires permission granted by Fluz per application; business registration requires the `REGISTER_BUSINESS` scope. Talk to your account manager before building against either.
</Warning>

***

## Do you need to do this at all?

You don't have to own onboarding. An [embedded widget](/developers/widgets) runs registration, verification, and consent as a hosted flow, keeping identity data inside Fluz's compliance scope.

|                                      | Widget        | API      |
| :----------------------------------- | :------------ | :------- |
| Who collects SSN, DOB, and documents | Fluz          | You      |
| Who carries that data at rest        | Fluz          | You      |
| User re-types data you already hold  | No            | No       |
| Control over presentation            | Branding only | Complete |
| Build cost                           | Hours         | Days     |

Register users yourself when you **already hold clean, verified profile data**. If you'd be collecting date of birth and SSN purely to forward them, use the widget — you're taking on regulated data handling for no benefit.

***

## The individual track

<Steps>
  <Step title="Register">
    `registerUser` with first name, last name, phone, region code, email, and date of birth (`YYYY-MM-DD`).

    Names should match the documents the user will verify with. A mismatch resurfaces at step 2 as a decline that's much harder to diagnose.

    → [User Registration](/user-registration)
  </Step>

  <Step title="Verify">
    `verifyUserInformation` runs KYC. Users must be verified to transact at all, or to transact at higher limits.

    → [User KYC Verification](/user-kyc-verification)
  </Step>

  <Step title="Get authorized">
    Registering someone does not give you permission to act for them. That's a separate, explicit grant.

    → [Client-facing OAuth grant flow](/client-facing-o-auth-grant-flow)
  </Step>
</Steps>

### Verification outcomes

| Status      | Meaning                                     | What to do                                                                                            |
| :---------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------- |
| `APPROVED`  | Verified                                    | Proceed                                                                                               |
| `DECLINED`  | Not verified                                | Re-check the submitted data against the user's documents, then retry — but see the attempt limit      |
| `DUPLICATE` | Verified, but the data matches another user | Verified, so you can proceed. Investigate before scaling — it often means one person onboarding twice |
| `ERROR`     | Attempt limit exceeded                      | **Three attempts maximum.** Stop retrying                                                             |

<Warning>
  **Three attempts, then the door closes.** Validate aggressively *before* calling — address formatting, name spelling, date format — because a typo burns one of three tries. Never put `verifyUserInformation` behind an automatic retry loop.
</Warning>

### "Already in use" is normal

`registerUser` returns `AUTH-0026` (phone) or `AUTH-0027` (email) when the person already has a Fluz account. Fluz accounts aren't scoped to your application, so anyone who has used Fluz before — through any app or the consumer product — already exists.

That's a routing signal, not a failure. Send them through the [grant flow](/client-facing-o-auth-grant-flow) to authorize the account they already have. Build this as the normal path, not an error branch.

***

## The business track

KYB has more moving parts and a strict order.

<Steps>
  <Step title="Register the primary owner as a user first">
    **This is the dependency people miss.** The primary business owner must already be a registered Fluz user, and the `emailAddress` on the owner record must be the one they registered with. Register the human before you register the company.
  </Step>

  <Step title="Fetch valid categories">
    `getBusinessCategories` returns the `businessCategoryId` and `businessSubCategoryId` values you'll need. Don't hard-code them, and don't mix a subcategory from one category with another — that's `BS-0006`.

    → [Business Categories](/business-categories)
  </Step>

  <Step title="Upload a document, if sole proprietorship">
    `SOLE_PROPRIETORSHIP` requires a supporting document, uploaded first via a REST endpoint as `form-data`. Pass the returned URL as `soleProprietorshipDocumentUrl`.
  </Step>

  <Step title="Register the business">
    `registerBusiness` with the entity details, legal address, tax ID, categories, account usage, and owners. Returns an `accountId` and a `kybStatus` of `PENDING`.

    → [Business Registration](/business-registration)
  </Step>

  <Step title="Wait for KYB to resolve">
    The account stays `PENDING` until verification completes.
  </Step>
</Steps>

### Constraints worth knowing before you build

| Constraint                        | Detail                                                                                                        |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| **One application at a time**     | A user with an in-flight business application can't start another until it's approved or rejected (`BS-0007`) |
| **Owners must be US-based**       | `OwnerAddress` requires a valid US state name and a 5-digit ZIP                                               |
| **Ownership can't exceed 100%**   | Summed across all owners                                                                                      |
| **Tax ID format is strict**       | `XX-XXXXXXX` — two digits, hyphen, seven digits (`BS-0001`)                                                   |
| **Some countries are restricted** | Certain jurisdictions can't be registered for KYB                                                             |
| **Account usage is required**     | Either `businessAccountUsage` (from the enum) or `businessAccountUsageOther`                                  |

<Warning>
  **Date of birth is formatted differently in the two flows.** `registerUser` takes `dateOfBirth` as `YYYY-MM-DD`. `BusinessOwner.dob` takes `MM/DD/YYYY`. Same concept, adjacent pages, opposite formats — and a wrong format here costs you a failed registration or a burned KYC attempt.
</Warning>

***

## Scopes and permissions

| Operation               | Requirement                                         |
| :---------------------- | :-------------------------------------------------- |
| `registerUser`          | Application-level permission granted by Fluz        |
| `verifyUserInformation` | See [User KYC Verification](/user-kyc-verification) |
| `registerBusiness`      | `REGISTER_BUSINESS` scope                           |
| `getBusinessCategories` | See [Business Categories](/business-categories)     |

Enable scopes on the app's **Permissions** tab before building. A scope you request but haven't enabled is silently dropped rather than rejected. → [Configure OAuth App](/configure-o-auth-app)

***

## Errors come back in `data`

Both `registerUser` and `registerBusiness` report failure as an HTTP 200 with `success: false` and a populated `error` object — **not** as entries in the GraphQL `errors` array. Code that only inspects `errors` will read every failure as a success.

Check all three layers: transport errors, then `success`, then branch on `error.code`.

| Family   | Covers                                                                      |
| :------- | :-------------------------------------------------------------------------- |
| `AUTH-*` | User registration — invalid phone, already in use, permission, app inactive |
| `BS-*`   | Business registration — tax ID, address, owners, category, usage, structure |
| `AR-*`   | Missing or invalid arguments                                                |
| `AU-*`   | General registration failure                                                |

***

## Handling the data

This section moves more regulated data than anywhere else in the API: full names, dates of birth, SSN digits, home addresses, identity documents.

* Send it from your server over TLS. Never from a browser or mobile client.
* Keep it out of logs, error-tracking payloads, and analytics.
* Validate formats locally before calling, both to avoid burning KYC attempts and to avoid transmitting data twice.
* Have an answer ready for how long you retain it and why. Your enterprise customers will ask.

If none of that is appealing, that's the case for the [widget](/developers/widgets).

***

## Testing

Staging mirrors these flows without real verification against real people. **Never register real individuals or businesses in staging**, and never carry staging test identities into production.

→ [Testing KYC Flows](/test-kyc-flows) · [Test Addresses](/test-addresses) · [Staging vs. Live](/concepts/environments)

***

## In this section

<CardGroup cols={2}>
  <Card title="User registration" icon="user-plus" href="/user-registration">
    Create an individual account.
  </Card>

  <Card title="User KYC verification" icon="badge-check" href="/user-kyc-verification">
    Verify the person behind it.
  </Card>

  <Card title="Business registration" icon="building-2" href="/business-registration">
    Create an entity and start KYB.
  </Card>

  <Card title="Business categories" icon="tags" href="/business-categories">
    Valid category and subcategory IDs.
  </Card>

  <Card title="Formatting referral links" icon="link" href="/formatting-referral-links">
    Bring users in through a referral.
  </Card>

  <Card title="Embedded widgets" icon="layout-template" href="/developers/widgets">
    Hand the whole flow to Fluz instead.
  </Card>
</CardGroup>