Partners Verifications Guide
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#
- Verification of Income (Doc VOI)
- Verification of Assets (VOA)
- Verification of Income (VOI)
- Verification of Assets & Income (VOAI)
- Verification of Employment (VOE)
Workflow#
Argyle's Postman collection contains examples of the endpoints mentioned below.
Create a user#
Create a user before ordering both document and banking verifications.
Order a verification#
Order a verification using POST /partners/v2/verifications.
Banking 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.
Use banking.link returned in the response to launch the Mastercard Connect experience. Render the link in an iframe or redirect the user to it, allowing the user to connect their financial accounts.
Parameters:
client— client UUID (required)verification— verification ID (required)banking.experience— experience ID (optional)banking.single_use_url— expires after a successful connection (optional)banking.redirect_url— redirect URL after the session (optional)
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:
pendinguser_session_started(banking)authenticated(banking)completed
Retrieve reports#
When status.state is COMPLETED, retrieve the report using file_url (PDF) or 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.
This is optional and is intended to refresh data without a new Connect session.
Recovery options & error handling#
User abandons session
If the user closes the banking Connect flow before completion, generate a new session URL for the same verification:
POST /partners/v2/sessions
PII mismatch / creation failure
If POST /partners/v2/verifications returns a 400 error (missing or invalid user details):
- Update the user with
PATCH /partners/v2/users/{id} - Retry
POST /partners/v2/verifications
Testing#
Documents#
Sandbox
Production
Production testing can be done with real documents. If needed, the below test documents can also be used.
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 — the
FinBank Profiles AorFinBank Profiles Bfinancial institutions - Production — the
FinBank BillableorFinBank Oauth Billablefinancial institutions
| 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 (failed report) voi (failed report) voai (failed report) |
For specific scenario testing, the following sample test 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. |