Overview - Fluz

registerUser provisions a Fluz account for someone using profile data you already hold — no redirect, no hosted form, no asking the user to re-type their name and date of birth.

Restricted access. This mutation requires explicit permission from Fluz. Contact your account manager to enable user registration for your application. Calls from an application without it fail with AUTH-0022.

Where this fits

Registration is one step of an onboarding arc, and it’s optional — you can hand the whole thing to a widget instead.

Approach	Registration	Consent	KYC	Build cost
Widget	Hosted by Fluz	Hosted by Fluz	Hosted by Fluz	Hours
Hybrid	`registerUser`	Widget or redirect	`verifyUserInformation`	Days
API only	`registerUser`	OAuth redirect	`verifyUserInformation`	Days, plus you handle the PII

Register users yourself when you already hold clean profile data and don’t want the user typing it twice. If you’d be collecting name, date of birth, and contact details purely to pass them to Fluz, use an embedded widget instead — it keeps that collection inside Fluz’s compliance scope. The full sequence for the API path:

registerUser with name, phone, email, and date of birth.

Get authorized

The user signs in and grants your application scopes. → Client-facing OAuth grant flow

Verify

Mint a user access token and run KYC with verifyUserInformation, or hand the user a document verification link. → User KYC Verification

Operate

Mint a user access token and use the API on their behalf. → Authentication

Registering a user grants your application nothing. Until the user completes the OAuth grant, you can’t act for them: generateUserAccessToken and getAccountsByUserId fail with AUTH-0031, and the user doesn’t appear in getApplicationUsers. That includes KYC — authorization comes before verification, not after.

Fluz turns consent mode on per application. Contact your account manager to switch.

In consent mode, registerUser creates no user, account, or grant when you call it. It returns a link where the person signs up or logs in with the phone number you submitted and approves your application’s scopes, all in one flow. When they approve, your application holds the grant, so there is no separate authorization step and no “already in use” branch to handle. One exception: if the person’s Fluz account is already linked to your application under a different externalReferenceId, approval fails unless your application allows multiple external links. Approval also fails if the person signs in with a different phone number from the one you submitted, so submit the number they use with Fluz.

mutation RegisterUser(
  $firstName: String!
  $lastName: String!
  $phoneNumber: String!
  $regionCode: String!
  $emailAddress: String!
  $externalReferenceId: String!
  $steps: [RegisterUserEnrollmentStep!]
  $callbackUrl: String
) {
  registerUser(
    firstName: $firstName
    lastName: $lastName
    phoneNumber: $phoneNumber
    regionCode: $regionCode
    emailAddress: $emailAddress
    externalReferenceId: $externalReferenceId
    steps: $steps
    callbackUrl: $callbackUrl
  ) {
    success
    status
    authorizationUrl
    expiresAt
    userId
    accountId
    error {
      code
      message
    }
  }
}

Parameter	Required	Description
`firstName`, `lastName`, `phoneNumber`, `regionCode`, `emailAddress`	Yes	As for direct registration. The link pre-fills the phone number
`externalReferenceId`	Yes	Your own ID for this person. It’s stored on the grant. See Managing External Reference IDs
`steps`	No	Setup steps after consent, in order: `KYC`, `FUNDING_SOURCE`, `PIN`. Leave it out to end the flow at consent. See Enrollment widget
`callbackUrl`	No	An `https` URL for the Back to app button at the end of the flow

dateOfBirth, billingAddress, and acceptCardholderAgreement are not used. List KYC in steps to have the person verify their identity in the flow. Add the billing address with addVirtualCardAddress after the grant. The response depends on whether your application already holds a grant for this externalReferenceId:

`status`	Meaning	What to do
`PENDING_CONSENT`	No grant yet. Returned the same way whether or not the person already has a Fluz account	Show `authorizationUrl` before `expiresAt`. Once the person approves, call `generateUserAccessToken` with your `externalReferenceId`. `OAUTH_USER_LINKED` usually signals this, and calling `registerUser` again returns `LINKED`
`LINKED`	The grant already exists. `userId` and `accountId` are returned, with no link	Call `generateUserAccessToken` with your `externalReferenceId`

Send authorizationUrl only to the person you registered, and treat it like a sign-in link. It carries the name, email address and phone number you submitted, and anyone who has it can open it.

Each call returns a new link, and nothing is stored until the person approves, so an expired or unused link needs no cleanup. Call registerUser again to get a new one. The full field and error reference is on registerUser.

The mutation

mutation RegisterUser(
  $firstName: String!
  $lastName: String!
  $phoneNumber: String!
  $regionCode: String!
  $emailAddress: String!
  $dateOfBirth: String!
  $billingAddress: VirtualCardBillingAddressInput!
  $acceptCardholderAgreement: Boolean!
) {
  registerUser(
    firstName: $firstName
    lastName: $lastName
    phoneNumber: $phoneNumber
    regionCode: $regionCode
    emailAddress: $emailAddress
    dateOfBirth: $dateOfBirth
    billingAddress: $billingAddress
    acceptCardholderAgreement: $acceptCardholderAgreement
  ) {
    success
    userId
    accountId
    billingAddressId
    error {
      code
      message
    }
  }
}

error is an object (RegisterUserError), not a string — always select code and message as subfields. Requesting bare error won’t compile.

Parameters

Parameter	Type	Required	Description
`firstName`	String	Yes	The user’s first name
`lastName`	String	Yes	The user’s last name
`phoneNumber`	String	Yes	Digits and `-` accepted — `"5551234567"` or `"555-123-4567"`. This is the number the user receives sign-in codes on, so it must be a real mobile number in production
`regionCode`	String	Yes	ISO 3166-1 alpha-2 country code for the phone number, e.g. `"US"`
`emailAddress`	String	Yes	Must not already exist on a Fluz account
`dateOfBirth`	String	Yes	`YYYY-MM-DD`
`billingAddress`	VirtualCardBillingAddressInput	Yes	The user’s billing address (`streetAddressLine1`, `city`, `state`, `postalCode`, `country`). Validated, saved for the user’s virtual cards, and returned as `billingAddressId`
`acceptCardholderAgreement`	Boolean	Yes	Must be `true` — registration is rejected otherwise
`deferSeatAssignment`	Boolean	No	Leave this out for platform onboarding. When `true`, creates the user without a rewards-network seat, which is assigned later at card redemption (see Register & Send). A user created this way can’t be used for the authorize → verify → operate path: `generateUserAccessToken` for them fails with `AUTH-0008`

Names should match the identity documents the user will verify with — a mismatch surfaces later as a KYC failure that’s much harder to diagnose than a registration error.

What gets created

A complete Fluz account: the user record, their wallet and balances, and their rewards eligibility. There’s nothing further to provision before the user can authorize your app.

Handling the response

Failures come back in data, not in errors. A failed registration is an HTTP 200 with success: false. Code that only checks the GraphQL errors array will read every failure as a success.

Success

{ "data": { "registerUser": { "success": true, "error": null } } }

Failure

{
  "data": {
    "registerUser": {
      "success": false,
      "error": {
        "code": "AUTH-0026",
        "message": "The phone number you chose is already in use."
      }
    }
  }
}

A handler that gets all three layers right:

const res = await fetch(FLUZ.graphqlUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({ query: REGISTER_USER, variables: profile }),
});

const body = await res.json();

// 1. Transport and GraphQL-level failures
if (body.errors?.length) {
  throw new Error(`GraphQL error: ${body.errors[0].message}`);
}

const result = body.data.registerUser;

// 2. Business-level failure — still an HTTP 200
if (!result.success) {
  switch (result.error.code) {
    case 'AUTH-0026':
    case 'AUTH-0027':
      // Not a failure. This person already has a Fluz account.
      return routeToAuthorization(profile);

    case 'AUTH-0004':
      return promptForValidPhoneNumber();

    case 'AUTH-0022':
    case 'AUTH-0030':
      // Configuration problem on your side — don't retry, alert.
      throw new ConfigurationError(result.error.code);

    default:
      throw new RetryableError(result.error.message);
  }
}

// 3. Success — the next step is authorization, not verification
return routeToAuthorization(profile);

“Already in use” is a routing signal, not an error

AUTH-0026 (phone) and AUTH-0027 (email) mean the person already has a Fluz account. That’s a normal, expected outcome — Fluz accounts are not scoped to your application, so anyone who has used Fluz before, through any app or the consumer product, already exists. Treating this as a failure is the most common integration mistake here. The right response is to stop trying to create an account and start asking for access to the existing one: send the user through the OAuth grant flow, or open a widget. They log in to the account they already have and authorize you. Design your onboarding so the register-then-fall-back path is the normal case rather than an exception branch, and it stays clean at scale. Both branches end in the same place: the user authorizes your app.

Retries and duplicates

registerUser takes no idempotency key. A retry is a genuinely new attempt, and a timeout is an unknown outcome.

If a call times out or the connection drops, the registration may well have succeeded. Retrying the identical request then returns AUTH-0026 — which is indistinguishable from the user having had an account all along. That ambiguity is harmless as long as you treat both the same way: on timeout, retry once, and route AUTH-0026 / AUTH-0027 to authorization rather than to an error state. Either the account you just made or the account that already existed ends up authorized, which is the outcome you wanted. What you must not do is surface “phone number already in use” to a user who just gave you their number for the first time.

How a registered user signs in

A user created with registerUser has no password. When you send them to /authorize, Fluz signs them in with a one-time code sent by SMS to the phoneNumber you registered.

It’s an SMS code, not a TOTP code. Authenticator apps such as Authy or Okta Verify can’t produce it.
In staging, no SMS is sent. Enter 123456 as the code for any user you registered.
If the code is rejected in staging, check that the user is signing in with the same phone number you registered, then share the full /authorize URL with your Fluz contact.

After registration

A registered account is not yet an authorized or verified one. Before the user can move money, in this order:

An authorization grant. Registering someone doesn’t give you permission to act for them — that’s a separate, explicit step the user completes. → Client-facing OAuth grant flow
Your own identifier attached. Pass external_id on the authorization so you can address this person by your own user ID from then on. → Managing External Reference IDs
Identity verification. With a token from the grant, pass the SSN and address you hold to verifyUserInformation, or issue a document verification link for the user to complete. → User KYC Verification

Known issue — business applicants created with registerUser. Some users created with registerUser are missing an OAuth setting, so registerBusiness fails with AUTH-0008 (“does not have permission to access the application”) even after a valid grant. Until the fix ships, send the user through /authorize once, choose Apply for a business account on the account picker, and reuse the same external_id as their existing grant. generateUserAccessToken tokens then work for registerBusiness. If it still fails, contact your Fluz contact with the user ID.

Handling the data

You’re transmitting full name, date of birth, email, and phone number — a set that identifies a real person. Send it over TLS from your server, keep it out of logs and error-tracking payloads, and don’t echo it back in client-visible responses. Note that date of birth in particular is regulated identity data in most jurisdictions, and it stays sensitive on your side after the call succeeds. If you’d rather not hold any of it, that’s the argument for the widget — Fluz collects it inside its own compliance scope and you never touch it.

Error codes

From `registerUser`

AUTH-0026 and AUTH-0027 are never returned in consent mode.

Code	Meaning	What to do
`AUTH-0004`	Phone number invalid or unparseable for the given `regionCode`	Fix the input. Check `regionCode` matches the number’s country
`AUTH-0022`	Your application isn’t permitted to register users	Contact your account manager. Don’t retry
`AUTH-0025`	General registration failure	Retryable. Escalate if it persists
`AUTH-0026`	Phone number already on an account	Route to authorization — see above
`AUTH-0027`	Email already on an account	Route to authorization — see above
`AUTH-0030`	Your application is not active (for example, status `PERSONAL`)	Use an OAuth Integration application that Fluz has moved to `ACTIVE`. See Prepare Your Accounts. Don’t retry
`WIDGET-003`	Consent mode: your application has no OAuth client, or no API key and secret to sign the link	Contact your account manager. Don’t retry

Right after registration

Code	Where you see it	Cause	What to do
`AUTH-0031`	`generateUserAccessToken`, `getAccountsByUserId`	The user hasn’t completed the OAuth grant	Send the user through the grant flow
`AUTH-0008`	`generateUserAccessToken`	The user was registered with `deferSeatAssignment: true`	Register without the flag
`AUTH-0008`	`registerBusiness`	Known issue for users created with `registerUser`	See the known-issue note above

Environments

Point at the GraphQL host for your environment — https://transactional-graph.staging.fluzapp.com/api/v1/graphql for staging, https://transactional-graph.fluzapp.com/api/v1/graphql for production. Registration permission is granted per application, so a production app needs it enabled separately. → Deploying to Production Never register real people in staging. → Staging vs. Live

Next steps

Grant flow

Get permission to act on their behalf.

User KYC verification

Verify the account you just created.

External reference IDs

Address them by your own user ID.

Embedded widgets

Hand the whole onboarding to Fluz instead.

​Where this fits

​Consent mode

​The mutation

​Parameters

​What gets created

​Handling the response

​“Already in use” is a routing signal, not an error

​Retries and duplicates

​How a registered user signs in

​After registration

​Handling the data

​Error codes

​From registerUser

​Right after registration

​Environments

​Next steps

Grant flow

User KYC verification

External reference IDs

Embedded widgets

Where this fits

Consent mode

The mutation

Parameters

What gets created

Handling the response

“Already in use” is a routing signal, not an error

Retries and duplicates

How a registered user signs in

After registration

Handling the data

Error codes

From `registerUser`

Right after registration

Environments

Next steps