> ## 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.

# Owner Verification Link

> Generate a shareable identity-verification link for a business owner who must verify by document.

## 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](/business-status) 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.

<Note>
  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.
</Note>

## 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:

<Steps>
  <Step title="A business-account token with REGISTER_BUSINESS">
    Scoped to the business that owns the roster.
  </Step>

  <Step title="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](/business-status) reports all of those as `kybStatus: PENDING`. See [Timing](#timing).
  </Step>

  <Step title="businessOwnerId is the owner's business-user ID">
    Taken from `owners[].id` in [getBusiness](/business-status), and belonging to this business. A Fluz user ID is not accepted, and invited owners who have not accepted have `id: null`.
  </Step>

  <Step title="The owner is on the document path">
    `verificationType: DOCUMENTS` with `status: PENDING_CIP`.
  </Step>
</Steps>

## Basic mutation structure

```graphql theme={null}
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](/business-status). 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 |

<Note>
  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](/business-registration), which reports validation failures inside its payload.
</Note>

## Timing

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

<Warning>
  **Call it early.** Shortly after `registerBusiness` returns, as soon as [getBusiness](/business-status) 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.
</Warning>

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

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

### Error

```json theme={null}
{
  "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](/business-status) for a current ID, and see [Timing](#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](/business-status).
* There is no bulk variant. Call once per owner who needs a link.

## Related pages

<CardGroup cols={2}>
  <Card title="Business KYB status" href="/business-status">
    Identify which owners need a link, and confirm when they finish.
  </Card>

  <Card title="KYB overview" href="/kyb-overview">
    Where this step sits in the end-to-end flow.
  </Card>

  <Card title="Register a business" href="/business-registration">
    How `isUsPerson` puts an owner on the document path.
  </Card>
</CardGroup>