Verify by SSN

Passing Fluz the SSN information is the more direct of the two API methods. You collect a small set of identity fields from the customer and submit them, and Fluz returns a decision in the same response. Use it as your first API attempt whenever you already hold — or can reasonably ask for — the customer’s identity details. If it declines, escalate to requesting an IDV URL.

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. See Verify Customers.

How it works

The verifyUserInformation mutation is synchronous. You submit the customer’s information and Fluz screens it against identity data on file, returning APPROVED, DECLINED, DUPLICATE, or ERROR in the response body. There is no customer-facing step and nothing for the customer to complete. Fluz also emits a verification event to your webhook endpoint, so a single handler can process outcomes from every verification method consistently.

Request

The customer being verified is identified by the user access token in the Authorization header — you do not pass a user ID in the input.

Field	Type	Required	Description
`firstName`	String	Yes	The customer’s legal first name.
`lastName`	String	Yes	The customer’s legal last name.
`streetLine1`	String	Yes	Residential street address.
`streetLine2`	String	No	Apartment, suite, or unit. Pass an empty string if unused.
`city`	String	Yes	City.
`state`	String	Yes	State or region.
`postalCode`	String	Yes	ZIP or postal code.
`country`	String	Yes	Country.
`dateOfBirth`	String	Yes	Date of birth, formatted `MM/DD/YYYY`.
`ssnLast4`	String	Yes	The last four digits of the customer’s SSN.

Fluz accepts either the full SSN or just the last four digits. Submitting only the last four is recommended — it produces the same decision while reducing what you have to collect and store.

Submit the customer’s residential address, not a billing or mailing address. PO boxes are rejected. A mismatched address is the most common cause of a false decline — see Address Formatting Requirements.

Example

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

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

const VERIFY_USER_INFORMATION = gql`
  mutation verifyUserInformation($input: VerifyUserInformationInput!) {
    verifyUserInformation(input: $input) {
      status
      message
    }
  }
`;

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

const response = await client.request(VERIFY_USER_INFORMATION, {
  input: {
    firstName: 'John',
    lastName: 'Smith',
    streetLine1: '123 Main St',
    streetLine2: '',
    city: 'Los Angeles',
    state: 'CA',
    postalCode: '91234',
    country: 'United States',
    dateOfBirth: '01/28/1975',
    ssnLast4: '1234',
  },
});

console.log(response);

Response

{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

Open the recipe

A copy-and-run version of this example, ready to adapt to your integration.

Handling the response

Status	What to do
`APPROVED`	The customer is verified. Unlock the relevant functionality.
`DECLINED`	Escalate to document verification. Do not re-submit the same information.
`DUPLICATE`	The customer is verified, but their SSN matches another Fluz customer. Treat as verified and review for duplicate accounts on your side. Fluz does not disclose which customer matched.
`ERROR`	Inspect `message`. The customer is either already verified or has exhausted their attempts.

A customer may attempt SSN verification up to 3 times. After the third attempt, further requests return ERROR with Exceeded user verification limit. Move the customer to document verification rather than retrying.

Testing

Staging test identities return specific, deterministic result codes so you can exercise declines — address mismatch, deceased subject, thin file, invalid SSN, and others — without using real data. See Testing KYC Flows.

Do not modify the test identity data. Any field that does not match the expected test values will return a no-match rather than the result code you are trying to exercise.

​How it works

​Request

​Example

Open the recipe

​Handling the response

​Testing

How it works

Request

Example

Handling the response

Testing