Skip to main content

​
Introduction

This guide covers the verifications workflow:
  1. Create a user.
  2. Create a verification for your desired report type.
  3. Create and launch a frontend session (payroll and banking only).
  4. Listen for lifecycle updates via verifications.updated.
  5. Retrieve the completed report PDF and JSON.

​
Supported report types

​
Example reports

PDFReport PDF
Image of Argyle's Verification of Income and Employment (VOIE) report.
PDF
Image of Argyle's Verification of Income and Employment (Government Payroll VOIE) report.
PDFReport PDF
Image of Argyle's Verification of Employment (VOE) report.
PDFReport PDF
Image of Verification of Assets (VOA) banking report.
PDFReport PDF
Image of Verification of Assets & Income (VOAI) banking report.
PDFReport PDF
Image of Verification of Income (VOI) banking report.
PDFReport PDF
Image of Verification of Employment (Banking VOE) banking report.
PDFReport PDF
Image of Verification of Income (Doc VOI) 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.

​
Government Overview

Generate government payroll reports with voie-government. If self-certification is enabled, applicants review their income in Link before submitting.
Applicant self-certification flow for a government payroll report.

​
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

Doc VOI reports are designed for mortgage workflows and typically require a recent paystub plus prior-year year-end income documents, such as W-2s or December paystubs. For non-mortgage document collection, OCR, and authenticity workflows, use Document Processing.
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
Argyle Doc VOI report PDF

​
Workflow

​
Create a user

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

​
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, banking, or documents-based.
  • employments is required for document verifications only.
  • report.configuration is used for banking verifications only.
  • loan and billing apply to regular payroll and mortgage verification workflows.
Payroll verifications use report.type = voie | voe
Government payroll verifications use report.type = voie-government.
  • Set report.self_certification = false when applicant review and confirmation are not required.
Banking verifications use report.type = voa | voai | voi | voe-transactions
Mortgage document verifications use report.type = doc-voi-mortgage

​
Create a connection session

Skip this step for document verifications. For payroll and banking verifications, create a session via POST /v2/sessions. When the request succeeds, the response includes a link URL that launches the frontend session. Session links expire after one hour for security. A new session link can be created at any time by creating another session for the active verification.
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 propertyApplies toDescription
configuration.experienceBanking onlyOptional bank connection experience customization ID
(provided by Argyle)
configuration.single_use_urlBanking onlyExpires after one successful connection
configuration.redirect_urlPayroll and bankingRedirect URL after session completion.
configuration.flow_idPayroll onlyOptional payroll embedded connection experience customization ID
configuration.itemsPayroll onlyLimits Link to the provided Items. One Item opens that Item directly; multiple Items show only those Items.
configuration.languagePayroll onlySupported Link display language
configuration.mobile_appPayroll onlySet to true if embedding in a mobile application, otherwise false

​
Launch the frontend session

Use the returned link based on the verification type.

​
Payroll

  • Payroll SDKs (recommended)
  • Hosted Link
    • On web, open the link URL in the same tab, a popup window, or a separate tab.
    • On mobile, open the link in a secure browser context such as ASWebAuthenticationSession on iOS or Android Custom Tabs on Android.
    • Hosted Link currently does not support callbacks.

​
Banking

  • Banking SDK (recommended)
    • Pass link as the connectURL value when launching the banking SDK.
    • SDK callbacks support immediate frontend UX handling. For backend verification status, subscribe to the verifications.updated webhook.
    • For SDK installation options and advanced configuration, refer to SDK docs.
  • Hosted banking session
    • Hosted or no-SDK banking flows must be enabled by Argyle before use. Reach out to your Argyle customer success manager before using this implementation path.
    • Set configuration.redirect_url so the user returns to your application.
    • On web, open the link URL in the same tab, a popup window, or a separate tab.
    • On mobile, open the link in a secure browser context such as ASWebAuthenticationSession on iOS or Android Custom Tabs on Android.
    • Do not default to opening the raw returned link directly in an iframe.

​
Subscribe to webhooks

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
  • awaiting_certification — awaiting user certification for aggregated government data
  • documents_processing — uploaded documents are currently processing
  • report_generating — the report is being generated
  • completed — the report is ready for download
  • completed_with_errors — the report is ready for download but has limitations
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 or completed_with_errors, the report object in the webhook payload will contain the following download links:
  • file_url — PDF report
  • json_url — report in JSON format
GET requests to file_url and json_url require Argyle authentication headers.

​
Re-Verifications

​
Instant Refresh

The refresh endpoint supports payroll, banking, and Doc VOI verifications. It 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. For Doc VOI, use the same endpoint with report.type = doc-voi-mortgage to generate a new report from the user’s existing uploaded documents without uploading additional documents. In most cases, instant refresh verifications move quickly to either completed or cancelled.

​
Doc VOI with new documents

To refresh a Doc VOI report with additional or updated documents, order a new doc-voi-mortgage verification for the same user with POST /v2/verifications. The request shape is the same as a new document verification, including the employments requirements. Argyle reuses the user’s previously uploaded documents as the baseline for the new verification. After the new verification is created:
  1. Upload each net-new document for the same user with POST /v2/user-uploads.
  2. Listen for verifications.updated webhooks as the verification moves through document processing.
  3. Retrieve the refreshed report from report.file_url or report.json_url when the verification is complete.

​
Recovery options and error handling

​
Connections not completed

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

​
User details missing or invalid

If POST /v2/verifications returns a 400 response for missing or invalid user details:
  1. Update the user with PATCH /v2/users/{id}.
  2. 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:

​
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
For specific scenario testing, the following sample users are also available:

​
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:
Do not adjust file names.
Upload only the following document: