Verify by Documents

Requesting an IDV URL is the higher-assurance API method, and the fallback when passing us the SSN information does not produce an approval. Rather than collecting identity documents yourself, you request a hosted verification link from Fluz and hand it to your customer. Fluz collects and screens the documents directly.

Prerequisites

The VERIFY_KYC scope enabled on your application by Fluz. See Required scope.
A user access token generated for the customer being verified, including VERIFY_KYC in its scopes.
A registered webhook endpoint. This is required for document verification — the outcome is not available in the API response. See Verify Customers.

How it works

You identify the customer and request a link

Call requestDocumentVerificationLink using a user access token generated for that customer. The token is what tells Fluz which customer the verification belongs to.

Fluz returns a verification link

The response contains a verificationUrl and a verificationId. Store the verificationId — it is how you reconcile the eventual webhook with this request.

You deliver the link to your customer

Send it however suits your product: email, SMS, push notification, or an in-app redirect. The customer can complete verification at any time.

Your customer uploads their documents

On the hosted page, the customer captures the front and back of a government-issued ID (driver’s license, passport, state ID, or military ID) and takes a selfie for a biometric match.

Fluz notifies you of the outcome

When the customer finishes, Fluz screens the submission and sends an APPROVED or DECLINED result to your webhook endpoint.

The verification link is unique to one customer and one verification attempt. Never reuse a link across customers, log it in a shared system, or expose it anywhere the intended customer is not the only reader — it grants access to an identity submission session.

Request

Field	Type	Required	Description
`gaveConsent`	Boolean	Yes	Whether the customer consented to identity verification. Must be `true`, or the request is rejected.
`prefillData`	Boolean	Yes	Whether to prefill the verification form with the identity information Fluz already holds. When `true`, you do not need to send the fields below.
`firstName`	String	No	The customer’s legal first name.
`lastName`	String	No	The customer’s legal last name.
`streetLine1`	String	No	Residential street address.
`streetLine2`	String	No	Apartment, suite, or unit.
`city`	String	No	City.
`region`	String	No	State or region.
`postalCode`	String	No	ZIP or postal code.
`country`	String	No	Country, in ISO 3166-1 alpha-2 format.
`dateOfBirth`	String	No	Date of birth, formatted `YYYY-MM-DD`.
`emailAddress`	String	No	The customer’s email address.
`phoneNumber`	String	No	The customer’s phone number in E.164 format.

You must capture and record the customer’s consent before setting gaveConsent: true. Anything you pass is used to prefill the form — the customer can review and correct it before submitting, so treat these fields as a convenience, not as the values that will be verified.

Note the field naming difference from SSN verification: this mutation uses region where the other uses state, and expects dateOfBirth as YYYY-MM-DD rather than MM/DD/YYYY.

Example

import { GraphQLClient, gql } from 'graphql-request';

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const REQUEST_DOC_VERIFICATION = gql`
  mutation RequestDocumentVerificationLink($input: RequestDocumentVerificationLinkInput!) {
    requestDocumentVerificationLink(input: $input) {
      userId
      verificationType
      verificationId
      verificationUrl
      status
      message
    }
  }
`;

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

const response = await client.request(REQUEST_DOC_VERIFICATION, {
  input: {
    gaveConsent: true,
    prefillData: true,
  },
});

console.log(response);

Response

{
  "data": {
    "requestDocumentVerificationLink": {
      "userId": "eb910e93-5e39-4f53-99b9-0b033dd8e54b",
      "verificationType": "DOCUMENT_VERIFICATION",
      "verificationId": "idv_9MpDJC8aotDaxw",
      "verificationUrl": "https://verify.fluz.app/idv/idv_9MpDJC8aotDaxw?key=27f09ec042881c2c56945680c53108a4",
      "status": "OK",
      "message": "Verification link request successful"
    }
  }
}

The status in this response (OK) confirms only that the link was issued — it is not the verification decision. The decision arrives later, by webhook.

Response fields

Field	Type	Description
`userId`	UUID	The Fluz customer the verification belongs to.
`verificationType`	String	Always `DOCUMENT_VERIFICATION`.
`verificationId`	String	Identifier for this verification attempt. Store it to reconcile the webhook.
`verificationUrl`	String	The hosted link to deliver to your customer.
`status`	String	`OK` when the link was issued successfully.
`message`	String	Human-readable detail.

What the customer sees

The hosted flow prefills known information for the customer to review, then asks them to:

Capture the front and back of a supported government-issued photo ID.
Take a selfie, which is matched biometrically against the ID photo.

Document authenticity, tampering, and the biometric match are all screened before a decision is returned.

Receiving the outcome

Because the customer may complete verification long after you issue the link, the outcome arrives at your webhook endpoint. Match the incoming event to your stored verificationId, then act on the result:

APPROVED — the customer is verified. Unlock the relevant functionality.
DECLINED — the customer is not verified. Document verification is the final step in the escalation path; a decline here generally requires manual review rather than another automated attempt.

Document verification requests are capped per customer. Once the limit is reached, further requests return ERROR with Exceeded document verification limit.

Testing

In staging you can complete the full document flow using sample driver’s licenses and test identities. Document authenticity and other security features are not enforced in staging, and you may reuse the front image for the back capture. See Testing KYC Flows.

​How it works

​Request

​Example

​Response fields

​What the customer sees

​Receiving the outcome

​Testing

How it works

Request

Example

Response fields

What the customer sees

Receiving the outcome

Testing