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

# Verify by SSN

> Submit a customer's legal name, address, date of birth, and last four SSN digits for an immediate identity decision.

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](/verify-customers-by-documents).

<Info>
  **Prerequisites**

  * The `VERIFY_KYC` scope enabled on your application by Fluz. See [Required scope](/user-kyc-verification#required-scope).
  * A [user access token](/recipes/generate-user-access-token) generated for the customer being verified, including `VERIFY_KYC` in its scopes.
  * A registered webhook endpoint. See [Verify Customers](/user-kyc-verification#set-up-a-webhook).
</Info>

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

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

<Warning>
  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](/concepts/address-formatting-requirements).
</Warning>

## Example

```javascript theme={null}
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);
```

```json Response theme={null}
{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}
```

<Card title="Open the recipe" icon="code" horizontal href="/recipes/verify-user-kyc">
  A copy-and-run version of this example, ready to adapt to your integration.
</Card>

## Handling the response

| Status      | What to do                                                                                                                                                                                  |
| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `APPROVED`  | The customer is verified. Unlock the relevant functionality.                                                                                                                                |
| `DECLINED`  | Escalate to [document verification](/verify-customers-by-documents). 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.                                                                                                 |

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

## 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](/test-kyc-flows).

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