Verifications Quickstart

A verification follows five steps:

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

This Quickstart uses a payroll voie verification as the example. The same lifecycle applies to the other verification types.

Before you begin

Create Sandbox API keys in Console.
Use the Sandbox base URL: https://api-sandbox.argyle.com/v2.
Send API requests from your backend using HTTP basic authentication.
Set up webhook handling, then subscribe to the verifications.updated webhook before testing the complete workflow.

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 and store the returned ID with your internal record. Before adding another product, update the existing 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

{
  "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. Set report.type to the required report type.

{
  "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:

For government programs, see 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 instead. The verification must be active. An active verification is not completed or cancelled.

Embedded session

Use POST /v2/sessions 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.

Payroll request: POST /v2/sessions

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "redirect_url": "https://your-application.com/return",
    "flow_id": "12ABCD3E",
    "language": "EN",
    "mobile_app": true
  }
}

Banking request: POST /v2/sessions

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "experience": "97f1eccb-241d-4052-8409-fab2dcc489b",
    "single_use_url": false,
    "redirect_url": "https://your-application.com/return"
  }
}

Payroll response

{
  "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"
}

Banking response

{
  "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"
}

See the Create a Session endpoint for every available request field.

Invites

To send the user an email, text message, or both, create an invite session with POST /v2/sessions and set type to invite. The user must have at least one active payroll or banking verification.

{
  "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.

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.

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 or 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 for the SDK example and hosted-session requirements.

Track status and retrieve the report

Listen for the verifications.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.

Overview

Verifications

Data APIs

Workflows

Integrations

Day 1 Certainty® and AIM

OCR and Authenticity

Console

Link

API Guide

Verifications Quickstart

Before you begin

Create or reuse a user

Order a verification

Create a session

Embedded session

Invites

Launch an embedded session

Payroll

Banking

Track status and retrieve the report

​Before you begin

​Create or reuse a user

​Order a verification

​Create a session

​Embedded session

​Invites

​Launch an embedded session

​Payroll

​Banking

​Track status and retrieve the report

Before you begin

Create or reuse a user

Order a verification

Create a session

Embedded session

Invites

Launch an embedded session

Payroll

Banking

Track status and retrieve the report