> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifications Quickstart

> Build your first verification workflow.

A verification follows five steps:

1. Create or reuse a user.
2. Order a verification.
3. Start a session when the user needs to connect an account.
4. Listen for verification status changes.
5. Retrieve the completed report.

This Quickstart uses a payroll `voie` verification as the example. The same lifecycle applies to the other [verification types](/verifications/overview#verification-types).

## Before you begin

* Create Sandbox API keys in [Console](https://console.argyle.com/api-keys).
* Use the Sandbox base URL: `https://api-sandbox.argyle.com/v2`.
* Send API requests from your backend using [HTTP basic authentication](/api-guide/overview#authentication).
* Set up [webhook handling](/api-guide/webhooks), then subscribe to the [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhook before testing the complete workflow.

<a id="create-a-user" />

## Create or reuse a user

If the person already has an Argyle user with your organization, reuse that user ID across payroll, banking, and document workflows. Otherwise, [create a user](/api-reference/users/create-a-user) and store the returned ID with your internal record.

Before adding another product, [update the existing user](/api-reference/users/update-a-user) with any missing details required by that product. Use the same user ID when ordering the verification.

Required user details depend on the verification type:

| Field          | Payroll      | Banking                                    | Doc VOI      |
| -------------- | ------------ | ------------------------------------------ | ------------ |
| `first_name`   | Required     | Required                                   | Required     |
| `last_name`    | Required     | Required                                   | Required     |
| `ssn`          | Not required | Required if `birth_date` is not provided   | Required     |
| `birth_date`   | Not required | Required if `ssn` is not provided          | Not required |
| `address`      | Not required | Required                                   | Not required |
| `email`        | Not required | Required if `phone_number` is not provided | Not required |
| `phone_number` | Not required | Required if `email` is not provided        | Not required |

```json theme={}
{
  "first_name": "Jane",
  "last_name": "Doe",
  "ssn": "000-00-0000",
  "email": "jane@example.com",
  "phone_number": "+15555555555",
  "address": {
    "city": "New York",
    "line1": "123 Main St",
    "line2": null,
    "state": "NY",
    "country": "US",
    "postal_code": "10001"
  },
  "birth_date": {
    "year": 1990,
    "month": 1,
    "day": 13
  }
}
```

Store the returned user `id`. The user ID is required when ordering the verification.

## Order a verification

Use [`POST /v2/verifications`](/api-reference/verifications/order-a-verification). Set `report.type` to the required report type.

```jsonc theme={}
{
  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
  "configuration": {
    "notified_recipients": [
      "john.doe@mortgage.com"
    ]
  },
  "report": {
    "type": "voie"
  },
  "loan": {      // Optional
    "number": "1234",
    "borrower_id": "ABC789",
    "application_id": "2121313",
    "officer_email": "john.doe@mortgage.com"
  },
  "billing": {      // Optional
    "cost_center": "5"
  }
}
```

Store the returned verification `id`. Use the type-specific guides for additional request fields and examples:

* [Payroll](/verifications/verification-types/payroll)
* [Banking](/verifications/verification-types/banking)
* [Doc VOI](/verifications/verification-types/document-voi)

For government programs, see [Government Benefits](/verticals/government-benefits).

## Create a session

Payroll and banking verifications require a session when the user needs to connect an account. Doc VOI uses [document uploads](/verifications/verification-types/document-voi#upload-documents) instead.

The verification must be active. An active verification is not completed or cancelled.

### Embedded session

Use [`POST /v2/sessions`](/api-reference/verifications/create-a-session) with the verification ID. Session links expire after one hour. Create another session for the same active verification when a new link is required.

The session request depends on whether the user is connecting a payroll or financial account.

<AccordionGroup>
  <Accordion title="Payroll request: POST /v2/sessions">
    ```json theme={}
    {
      "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
      "configuration": {
        "redirect_url": "https://your-application.com/return",
        "flow_id": "12ABCD3E",
        "language": "EN",
        "mobile_app": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Banking request: POST /v2/sessions">
    ```json theme={}
    {
      "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
      "configuration": {
        "experience": "97f1eccb-241d-4052-8409-fab2dcc489b",
        "single_use_url": false,
        "redirect_url": "https://your-application.com/return"
      }
    }
    ```
  </Accordion>

  <Accordion title="Payroll response">
    ```json theme={}
    {
      "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
      "configuration": {
        "experience": null,
        "single_use_url": false,
        "redirect_url": "https://your-application.com/return",
        "flow_id": "12ABCD3E",
        "language": "EN",
        "mobile_app": true
      },
      "link": "https://connect.argyle.com/?...",
      "data_source": "payroll"
    }
    ```
  </Accordion>

  <Accordion title="Banking response">
    ```json theme={}
    {
      "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
      "configuration": {
        "experience": "97f1eccb-241d-4052-8409-fab2dcc489b",
        "single_use_url": false,
        "redirect_url": "https://your-application.com/return"
      },
      "link": "https://connect2.finicity.com?...",
      "data_source": "banking"
    }
    ```
  </Accordion>
</AccordionGroup>

See the [Create a Session endpoint](/api-reference/verifications/create-a-session) for every available request field.

### Invites

To send the user an email, text message, or both, create an invite session with [`POST /v2/sessions`](/api-reference/verifications/create-a-session) and set `type` to `invite`. The user must have at least one active payroll or banking verification.

```json theme={}
{
  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
  "type": "invite",
  "configuration": {
    "email": "jane.doe@example.com",
    "phone_number": "+15555555555"
  }
}
```

One invite can include one or more active payroll or banking verifications for the same user. Invite links expire after 180 days or when revoked.

<Note>
  For wholesale mortgage implementations, the default wholesale flow is selected when the user has `external_metadata.broker` and `configuration.flow_id` is omitted. A provided `flow_id` takes precedence.
</Note>

## Launch an embedded session

Use the returned session `link` according to the verification's data source.

### Payroll

* Pass `link` as `connectUrl` when initializing the [Web SDK](/link/initialization/web#initialize-with-connecturl) or [Mobile SDKs](/link/initialization/mobile-sdks).
* For Hosted Link, open the URL in a browser context. Hosted Link does not provide Link callbacks.

### Banking

* Pass `link` as `connectURL` when launching the banking SDK.
* Use SDK callbacks for immediate frontend handling and the `verifications.updated` webhook for backend lifecycle tracking.
* See [Banking Verifications](/verifications/verification-types/banking#choose-a-session-type) for the SDK example and hosted-session requirements.

## Track status and retrieve the report

Listen for the [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhook. When `status.code` is `completed` or `completed_with_errors`, retrieve the report from `report.file_url` or `report.json_url`.

Continue with [Verification Statuses](/verifications/verification-statuses).