Skip to main content
Implementation guide for banking and document-based income verifications.

​
Overview

Order banking and document-based income verifications for partners using /partners/v2 endpoints.
  • Documents (Doc VOI): Upload paystubs and W-2s to generate a Doc VOI report.
  • Banking: Connect a user’s financial institutions to generate VOA, VOI, VOAI, or VOE reports.

​
Supported report types

​
Workflow

Argyle’s Postman collection contains examples of the endpoints mentioned below.

​
1. Create a user

Create a user before ordering both document and banking verifications. 
{
  "client": "39096494-45c8-4fd8-9454-3d1cb2d62db7",
  "first_name": "Jane",
  "last_name": "Doe",
  "ssn": "123-45-6789",
  "dob": {
    "year": 1990,
    "month": 5,
    "day": 14
  },
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postal_code": "10001"
  },
  "phone_number": "+12125555555",
  "email": "[email protected]",
  "external_metadata": {
    "suppress_verification": true
  }
}

​
2. Order a verification

Order a verification using POST /partners/v2/verifications.

​
3. (Banking only) Create a session

Banking verifications require a session.
The verification used to create the session must be in an active state (not completed or cancelled). If no active verification exists, create a new one and use it to initialize the session.
{
  "client": "39096494-45c8-4fd8-9454-3d1cb2d62db7",
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "banking": {
    "experience": "97f1eccb-241d-4052-8409-fab9e27a589b",
    "single_use_url": false,
    "redirect_url": null
  }
}

{
  "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
  "banking": {
    "experience": "97f1eccb-241d-4052-8409-fab9e27a589b",
    "single_use_url": false,
    "redirect_url": null,
    "link": "https://connect2.finicity.com?..."
  }
}
Use banking.link returned in the response to launch the Mastercard Connect experience.

​
4. Subscribe to webhooks

Subscribe to verifications.updated webhooks to track progress.
When subscribing, set include_resource = true to receive the full verification object, including status state.
Useful status state values:
  • pending
  • user_session_started (banking)
  • authenticated (banking)
  • completed

​
5. Retrieve reports

When status.state is COMPLETED, retrieve the report using:
  • file_url (PDF)
  • json_url (JSON)

​
Banking-only

​
Re-verifications (Instant Refresh)

Use POST /partners/v2/verifications/refresh to generate a new banking verification without reconnecting the user, as long as an active bank connection exists.

​
Recovery options and error handling

User abandons session
  • Create a new session URL for the same verification via POST /partners/v2/sessions.
PII mismatch or creation failure
  1. Update the user with PATCH /partners/v2/users/{id}.
  2. Retry POST /partners/v2/verifications.

​
Testing

​
Documents sandbox scenarios

  1. Order a verification with employments set to an active Warehouse Services Inc employment.
  2. Upload:
  1. Order the same verification setup.
  2. Upload only:

​
Banking sandbox scenario

Use the user SSN below for sandbox testing: 
"ssn": "537-36-9895"
Expected flow:
  1. Order a verification with report.type set to a banking report type.
  2. Create a banking session.
  3. Complete the Connect flow.
  4. Wait for verifications.updated webhook updates.
  5. Retrieve the completed report from file_url or json_url.
  1. Order a verification with employments set to an active Warehouse Services Inc employment.
  2. Upload:
Documents production scenarios
Production testing can be done with real documents. If needed, the test documents below can also be used.
  1. Order a verification with employments set to an active Warehouse Services Inc employment.
  2. Upload:
  1. Order a verification with employments set to an active Warehouse Services Inc employment.
  2. Upload:
  1. Order the same verification setup.
  2. Upload only:

​
Banking

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 — FinBank Profiles A or FinBank Profiles B
  • Production — FinBank Billable or FinBank Oauth Billable
UsernamePasswordAccount TypesSupported Products
profile_02profile_02Savings, IRA, 401k, Credit Cardvoa, voi, voai
profile_03profile_03Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners)voa, voi, voai
profile_04profile_04Checking, 403B, 529, Rollover, Mortgagevoa, voi, voai
profile_05profile_05Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners)voa, voi, voai
profile_06profile_06Checking, Retirement, KEOGH, 457, Credit Cardvoa, voi, voai
profile_07profile_07Checking, Stocks, CD, Investment Tax-Deferred, Employee Stockvoa, voi, voai
profile_08profile_08Checking, Primary Savings, Money Market, 401A, Line of creditvoa, voi, voai
profile_09profile_09Checking, Savings, Checking Failed Report. Errors include 102, 103, 185voa (failed report)
voi (failed report)
voai (failed report)
For specific scenario testing, the following sample test users are also available:
FieldSue WealthyRiver PaycheckAlex Student
Usernamesue_wealthyriver_paycheckalex_student
Passwordprofile_700profile_703profile_704
DescriptionSue is a Product Manager with steady income, a mortgage, multiple investment accounts, and typical household, travel, and pet expenses.River works in construction, rents an apartment, has typical expenses, some savings, and no investments, loans, or credit cards. In some months, River’s expenses exceed his income.Alex works full-time with a good salary and is still repaying student loans. She has typical expenses, limited savings, and a new investment account.

​
Document FAQs

  • PDF, JPEG, PNG, HEIC file types accepted
  • 16MB max file size
  • No, additional criteria may not be met.
  • For example, calculations and rep and warrant relief are not given when there is excessive fluctuation in income over time.
  • 120 days
  • Variable.
  • Exact amount is 14 days from the pay date of the most recent paystub.
  • For example, if today is July 31, 2025 and the most recent paystub uploaded had a pay date of July 21, 2025, only 4 days of employment rep and warrant relief would be given.