Owner Verification Link

Overview

The requestOwnerDocumentVerificationLink mutation generates a shareable URL that a business owner can use to complete identity verification by document. The link works on its own — the owner does not need Fluz credentials. Use it for owners that getBusiness reports with verificationType: DOCUMENTS and status: PENDING_CIP. Those are beneficial owners or control persons submitted with isUsPerson: false, which puts them on the document path rather than the SSN path.

Owners on the SSN path (verificationType: SSN) do not need to use this mutation, and neither do invited owners who have not accepted yet — Fluz emails those owners directly and they verify themselves.

Required scopes

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

Use a token minted for the business account that registerBusiness returned.

Prerequisites

All of these must hold, or the call fails:

A business-account token with REGISTER_BUSINESS

Scoped to the business that owns the roster.

The case is in the submitted-for-screening state

The link can only be generated during one specific state after submission. Cases that are still being created, already waiting on screening results, or in manual review are rejected — even though getBusiness reports all of those as kybStatus: PENDING. See Timing.

businessOwnerId is the owner's business-user ID

Taken from owners[].id in getBusiness, and belonging to this business. A Fluz user ID is not accepted, and invited owners who have not accepted have id: null.

The owner is on the document path

verificationType: DOCUMENTS with status: PENDING_CIP.

Basic mutation structure

mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) {
  requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) {
    success
    id
    verificationLink
  }
}

Parameters

Parameter	Type	Required	Description
`businessOwnerId`	`UUID`	Yes	The owner’s business-user ID, as returned in `owners[].id` from getBusiness. Not a Fluz user ID

Response details

Field	Type	Description
`success`	`Boolean`	`true` when a link was generated
`id`	`UUID`	The `businessOwnerId` the link was generated for
`verificationLink`	`String`	Shareable Plaid IDV URL. Send this to the owner directly

Failures are returned as top-level GraphQL errors, not as success: false. Check the errors array, not just the data payload. This is the opposite of registerBusiness, which reports validation failures inside its payload.

Timing

The state requirement in prerequisite 2 is the most common reason this call fails, and it is not visible through kybStatus.

Call it early. Shortly after registerBusiness returns, as soon as getBusiness shows the owner as verificationType: DOCUMENTS with status: PENDING_CIP.If you receive ARG-0001 with business is not submitted for approval, the case has moved past — or has not yet reached — that window. Do not retry in a loop. Keep reading getBusiness, and contact your account manager with the accountId if an owner stays PENDING_CIP with no way to send them a link.

cURL Example

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) { requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) { success id verificationLink } }",
    "variables": { "businessOwnerId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
  }'

Example Response

Success

{
  "data": {
    "requestOwnerDocumentVerificationLink": {
      "success": true,
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "verificationLink": "https://verify.docs../..."
    }
  }
}

Error

{
  "errors": [
    {
      "message": "Invalid arguments received - business owner not found.",
      "extensions": {
        "code": "ARG-0001",
        "statusCode": 422
      }
    }
  ],
  "data": null
}

Error Codes

Code	Name	Description	How to resolve
`AUTH-0002`	InvalidCredentials	Basic auth was used; the token’s account type is not `BUSINESS`; the token is missing `userId` or `accountId`; or no business exists for that `accountId`	Use a token minted for the business `accountId`
`AUTH-0031`	InvalidScope	The token is missing the `REGISTER_BUSINESS` scope	Add the scope and re-mint the token
`ARG-0002`	MissingArguments	`businessOwnerId` was not supplied	Pass the owner’s business-user ID
`ARG-0001`	InvalidArguments	`businessOwnerId` does not match a business owner on this business, or the case is not in the submitted-for-approval state	Re-read getBusiness for a current ID, and see Timing
`G-0001`	InternalError	The verification provider returned no link, or the request to it failed	Retry once. If it persists, contact support with the `accountId`

Notes

The generated link is single-purpose. If the owner’s link expires or is lost, call the mutation again for a fresh one rather than reusing the old one.
Generating a link does not change the owner’s status. It moves to READY only once the owner actually completes verification — keep reading getBusiness.
There is no bulk variant. Call once per owner who needs a link.

Business KYB status

Identify which owners need a link, and confirm when they finish.

KYB overview

Where this step sits in the end-to-end flow.

Register a business

How isUsPerson puts an owner on the document path.

​Overview

​Required scopes

​Prerequisites

​Basic mutation structure

​Parameters

​Response details

​Timing

​cURL Example

​Example Response

​Success

​Error

​Error Codes

​Notes

​Related pages

Business KYB status

KYB overview

Register a business

Overview

Required scopes

Prerequisites

Basic mutation structure

Parameters

Response details

Timing

cURL Example

Example Response

Success

Error

Error Codes

Notes

Related pages