Verifications Guide

Introduction

This guide covers the verifications workflow:

Create a user.
Create a verification for your desired report type.
Create a connection frontend session URL (payroll and banking only).
Listen for lifecycle updates via verifications.updated.
Retrieve the completed report PDF and JSON.

Supported report types

Payroll: Generate voie, voe, voie-mortgage, or voe-mortgage reports.
Banking: Connect financial institutions to generate voa, voai, voi, or voe-transactions reports.
Documents (Doc VOI): Upload paystubs and W-2s to generate a doc-voi-mortgage report.

Payroll Overview

Verify income and employment by allowing users to directly connect their employers and payroll providers.

Link is where payroll accounts are connected through Argyle.

Banking Overview

Verify assets and income by allowing users to directly connect their financial institutions.

Verify assets and income with Argyle banking reports.

Documents Overview

Receive Freddie Mac monthly income calculations from uploaded paystubs and W2s.

Upload paystubs and W-2s when borrower cannot connect via Argyle with a direct payroll login
Generate an Argyle Doc VOI report with rep & warrant determination for income and employment

Workflow

Create a user

Create a user before ordering a verification. Include the following PII information in your request:

Field	Payroll verifications	Banking verifications	Document verifications
`first_name`	Not required	Required	Required
`last_name`	Not required	Required	Required
`ssn`	Not required	Required	Required
`birth_date`	Not required	Required	Not required
`address`	Not required	Required	Not required
`phone_number`	Not required	Required	Not required

Example request: POST /v2/users

{
  "first_name": "Jane",
  "last_name": "Doe",
  "ssn": "000-00-0000",
  "email": "[email protected]",
  "phone_number": "+15555555555",
  "address": {
    "city": "New York",
    "line1": "123 Main St",
    "line2": null,
    "state": "NY",
    "country": "US",
    "postal_code": null
  },
  "birth_date": {
    "year": 1990,
    "month": 1,
    "day": 13
  },
  "external_id": null,
  "external_metadata": {
    "suppress_verification": true
  }
}

Order a verification

Use POST /v2/verifications for all verification types (payroll, banking, and documents). The shared request model works as follows:

user is required for all verification requests.
report.type determines whether the verification is payroll-based, banking-based, or documents-based.
employments is required for document verifications only.
report.configuration is used for banking verifications only.
loan and billing can be supplied for all verification types.

Payroll verifications use report.type = voie | voe | voie-mortgage | voe-mortgage

Example payroll request: POST /v2/verifications

{
  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
  "report": {
    "type": "voie"
  },
  "loan": {
    "number": "1234",
    "borrower_id": "ABC789",
    "application_id": "2121313",
    "officer_email": "[email protected]"
  },
  "billing": {
    "cost_center": "5"
  }
}

Banking verifications use report.type = voa | voai | voi | voe-transactions

Example banking request: POST /v2/verifications

{
  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
  "report": {
    "type": "voai",
    "configuration": {
      "from_date": "2024-01-01T00:00:00Z",
      "income_stream_confidence_minimum": 50,
      "report_custom_fields": [
        {
          "label": "loanID",
          "value": "12345",
          "shown": true
        }
      ]
    }
  },
  "loan": {
    "number": "1234",
    "borrower_id": "ABC789",
    "application_id": "2121313",
    "officer_email": "[email protected]"
  },
  "billing": {
    "cost_center": "5"
  }
}

Document verifications use report.type = doc-voi-mortgage

Example document request: POST /v2/verifications

{
  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
  "employments": [
    {
      "employer": "Warehouse Services Inc",
      "status": "active",
      "hire_date": "2023-02-01",
      "termination_date": null
    }
  ],
  "report": {
    "type": "doc-voi-mortgage"
  },
  "loan": {
    "number": "1234",
    "borrower_id": "ABC789",
    "application_id": "2121313",
    "officer_email": "[email protected]"
  },
  "billing": {
    "cost_center": "5"
  }
}

Create a connection session

Skip this step for document verifications. For payroll and banking verifications, create a session via POST /v2/sessions and direct the user to the link URL in the response.

The verification used to create the session must be in an active state. Active means the verification is not completed and not cancelled. If no active verification exists, create a new verification first.

The request requires a verification ID and accepts an optional configuration object:

Configuration property	Applies to	Description
`configuration.experience`	Banking only	Optional bank connection experience customization ID (provided by Argyle)
`configuration.single_use_url`	Banking only	Expires after one successful connection
`configuration.redirect_url`	Payroll and banking	Redirect URL after session completion
`configuration.flow_id`	Payroll only	Optional payroll embedded connection experience customization ID
`configuration.language`	Payroll only	Supported Link display language
`configuration.mobile_app`	Payroll only	Set to `true` if embedding in a mobile application, otherwise `false`

Example payroll request: POST /v2/sessions

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "redirect_url": null,
    "flow_id": "12ABCD3E",
    "language": "EN",
    "mobile_app": true
  }
}

Example payroll response

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "experience": null,
    "single_use_url": false,
    "redirect_url": null,
    "flow_id": "12ABCD3E",
    "language": "EN",
    "mobile_app": true
  },
  "link": "https://connect.argyle.com/?...",
  "data_source": "payroll"
}

Example banking request: POST /v2/sessions

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "experience": "97f1eccb-241d-4052-8409-fab9e27a589b",
    "single_use_url": false,
    "redirect_url": null
  }
}

Example banking response

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "configuration": {
    "experience": "97f1eccb-241d-4052-8409-fab9e27a589b",
    "single_use_url": false,
    "redirect_url": null
  },
  "link": "https://connect2.finicity.com?...",
  "data_source": "banking"
}

Render link returned in the response in an iframe or redirect the user to it so they can complete the payroll or banking connection experience. Subscribe to the verifications.updated webhook to track lifecycle events.

Set include_resource = true so the webhook payload contains the full verification object inside data.resource.

The most important verification status.code updates are:

pending — verification created
user_session_started — user opened the payroll or banking experience
authenticated — the user authenticated for payroll or banking and data aggregation is starting
documents_processing — uploaded documents are currently processing
completed — the report is ready for download

These are the primary lifecycle updates. Additional state transitions can occur depending on the verification flow.

Download reports and JSON

When you receive a verifications.updated webhook with status.code = completed, the report object in the webhook payload will contain the following download links:

file_url — PDF report
json_url — report in JSON format

Example webhook

{
  "event": "verifications.updated",
  "name": "name-for-the-webhook-subscription",
  "data": {
    "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
    "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
    "resource": {
      "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
      "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
      "created_at": "2023-03-09T16:22:06.081Z",
      "updated_at": "2023-03-09T16:22:06.081Z",
      "channel": "api",
      "status": {
        "state": "COMPLETED",
        "code": "completed",
        "errors": []
      },
      "report": {
        "id": "2a14ce6f-3aed-4c15-8ea2-92a17b6edb95",
        "type": "doc-voi-mortgage",
        "file_url": "www.argyle.com/storagename/pdf",
        "json_url": "www.argyle.com/storagename/json"
      },
      "employments": [
        {
          "employer": "Starbucks",
          "status": "active",
          "hire_date": "2015-08-28",
          "termination_date": null
        }
      ],
      "loan": {
        "number": "1234",
        "borrower_id": "ABC789",
        "application_id": "2121313",
        "officer_email": "[email protected]"
      },
      "billing": {
        "cost_center": "5"
      },
      "data_source": "documents"
    }
  }
}

GET requests to file_url and json_url require Argyle authentication headers.

Re-Verifications (Instant Refresh)

The refresh endpoint supports payroll and banking verifications. It reuses the user’s existing connection data and returns a new verification ID and report.

Use POST /v2/verifications/refresh to create a new payroll or banking verification without the user needing to reconnect, as long as a valid connection is still available. In most cases, instant refresh verifications move quickly to either completed or cancelled.

Recovery options and error handling

Connections not completed

If the user closes the payroll or banking experience before completion, the verification usually remains in pending or user_session_started. In this case, create a new session URL for the existing verification with POST /v2/sessions.

User details missing or invalid

If POST /v2/verifications returns a 400 response for missing or invalid user details:

Update the user with PATCH /v2/users/{id}.
Retry POST /v2/verifications.

Testing

Payroll test profiles

Use Argyle’s sample user credentials in Link to connect to:

Sandbox: any employer or payroll provider
Production: Platformtronic or Employertronic

For specific scenario testing, the following sample users are also available:

	Homer Loanseeker	Suzi Builder	Andy Freddie
Email	homer_loanseeker@argyle.com	suzi_builder@argyle.com	andy_freddie@argyle.com
Username	homer_loanseeker	suzi_builder	andy_freddie
Password	passgood	passgood	passgood
Verification code	9081	9084	9088
Phone number	(800) 900-0101	(800) 900-0104	(800) 900-0108
Driver’s license #	D1230101	D1230104	D1230108
Returns	1 active employment	2 active employments	1 active and 1 terminated employment

Banking test profiles

When you’re ready to begin testing, contact your Argyle Customer Success Manager to enable banking permissions.

The Sandbox testing environment for banking supports a maximum of 500 users. To stay within this limit, implement user-management workflows and remove inactive users when they are no longer needed.

The following sample test profiles can be connected to:

Sandbox: connect to FinBank Profiles A or FinBank Profiles B
Production: connect to FinBank Billable or FinBank Oauth Billable

Username	Password	Account types	Supported products
profile_02	profile_02	Savings, IRA, 401k, Credit Card	`voa`, `voi`, `voai`
profile_03	profile_03	Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners)	`voa`, `voi`, `voai`
profile_04	profile_04	Checking, 403B, 529, Rollover, Mortgage	`voa`, `voi`, `voai`
profile_05	profile_05	Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners)	`voa`, `voi`, `voai`
profile_06	profile_06	Checking, Retirement, KEOGH, 457, Credit Card	`voa`, `voi`, `voai`
profile_07	profile_07	Checking, Stocks, CD, Investment Tax-Deferred, Employee Stock	`voa`, `voi`, `voai`
profile_08	profile_08	Checking, Primary Savings, Money Market, 401A, Line of credit	`voa`, `voi`, `voai`
profile_09	profile_09	Checking, Savings, Checking failed report. Errors include `102`, `103`, `185`.	`voa`, `voi`, `voai` (failed report)

For specific scenario testing, the following sample users are also available:

	Sue Wealthy	River Paycheck	Alex Student
Username	sue_wealthy	river_paycheck	alex_student
Password	profile_700	profile_703	profile_704
Description	Sue is working as a Product Manager with a good steady income, a mortgage, and multiple investment accounts. She has a loan account and leases a car. Sue travels a few times a year. She has typical expenses like groceries, clothes, entertainment, gym membership, car expenses, and she has a pet.	River works in construction. He rents an apartment and has typical expenses like groceries, clothes, entertainment, household and car expenses. He has some savings but no investments, no loans and no credit cards. In some months, River’s expenses exceed his income.	Alex is working full-time with a good salary but she is still paying off her student loan. She makes regular monthly repayments, but she still has over $30,000 to pay off. Alex has typical expenses like groceries, clothes, entertainment, household, and car expenses. She has limited savings and she has started an investment account.

Doc VOI test documents

When you’re ready to begin testing, contact your Argyle Customer Success Manager to enable document permissions.

Use the sample documents below for Doc VOI verifications. For all scenarios below, order a document verification with the following employments value:

"employments": [
  {
    "employer": "Warehouse Services Inc",
    "status": "active",
    "hire_date": "2023-02-01",
    "termination_date": null
  }
]

Do not adjust file names.

Sandbox
Production

GSE-eligible monthly income

Upload the following documents:

Not GSE-eligible monthly income

Upload the following documents:

Requires more data

Upload only the following document:

Warehouse_Services_Inc_paystub.pdf

Core Resources

Coverage

Data Sets

Reports

Workflows

Verifications

Partners Verifications

Webhooks

Receipts

Error Codes

Introduction

Supported report types

Payroll Overview

Banking Overview

Documents Overview

Workflow

Create a user

Order a verification

Create a connection session

Download reports and JSON

Re-Verifications (Instant Refresh)

Recovery options and error handling

Connections not completed

User details missing or invalid

Testing

Payroll test profiles

Banking test profiles

Doc VOI test documents

Core Resources

Coverage

Data Sets

Reports

Workflows

Verifications

Partners Verifications

Webhooks

Receipts

Error Codes

​Introduction

​Supported report types

​Payroll Overview

​Banking Overview

​Documents Overview

​Workflow

​Create a user

​Order a verification

​Create a connection session

​Subscribe to webhooks

​Download reports and JSON

​Re-Verifications (Instant Refresh)

​Recovery options and error handling

​Connections not completed

​User details missing or invalid

​Testing

​Payroll test profiles

​Banking test profiles

​Doc VOI test documents

Introduction

Supported report types

Payroll Overview

Banking Overview

Documents Overview

Workflow

Create a user

Order a verification

Create a connection session

Subscribe to webhooks

Download reports and JSON

Re-Verifications (Instant Refresh)

Recovery options and error handling

Connections not completed

User details missing or invalid

Testing

Payroll test profiles

Banking test profiles

Doc VOI test documents