--- title: "Order a verification" method: POST path: "/v2/verifications" --- # Order a verification `POST /v2/verifications` Orders a new verification. [Create a user](/api-reference/verifications-guide#create-a-user) or update an existing user with the required details before ordering payroll, government, banking, or document verifications. ## Request body - ClientVerificationCreateRequest — Request body for ordering a verification. - `user` and `report` are required for all requests. - `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. - `user` string, uuid, required — User ID for the verification. - `employments` ClientVerificationEmploymentRequest[] — List of employments for the user. Required for document verifications only. Not used for payroll or banking verifications. - `employer` string, required — Name of the employer. - `status` 'active' | 'previous', required — User's current employment status at this employer. - `hire_date` string, date, required — Employment start date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. - `termination_date` string, date, nullable — Employment end date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` when employment `status` is `active`. - `report` ClientVerificationCreateReportRequest, required — Report request configuration. - `type` 'voie' | 'voe' | 'voie-government' | 'voa' | 'voi' | 'voai' | 'voe-transactions' | 'doc-voi-mortgage', required — The type of report to generate. Payroll: - `voie` - Verification of Income and Employment. - `voe` - Verification of Employment. - `voie-government` - Government income verification. Banking: - `voa` - Banking verification of assets. - `voi` - Banking verification of income. - `voai` - Banking verification of income and assets. - `voe-transactions` - Banking verification of employment. Documents: - `doc-voi-mortgage` - Mortgage document-based verification of income, integrated with Freddie Mac's AIM Check. - `self_certification` boolean, nullable — For `voie-government` reports, controls whether the applicant reviews and confirms income details in Link. Set to `true` to enable applicant self-certification, or `false` to skip applicant certification. Defaults to `true` when omitted for `voie-government` reports. Requests that include this field for other report types return a `400` error. - `configuration` object — Optional banking report configurations. - `bank_accounts` string[] — List of [bank account](/api-reference/bank-accounts) IDs to be included in the report. - `from_date` string, date-time — Restrict report to data from on or after this datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - `VOAI` reports - controls the length of asset history - `VOA` reports - controls the length of asset history - `VOI` reports - controls the length of income history - `income_from_date` string, date-time — Restrict report to data from on or after this datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - `VOAI` reports - controls the length of income history - Does not apply to `VOA` or `VOI` reports. - `income_stream_confidence_minimum` integer — Limit income streams used in the report to those above this confidence value (`0-100` accepted). Only available for `VOI` and `VOAI` report types. - `report_custom_fields` ClientReportCustomField[] — Include up to `5` custom objects in the report metadata. Often used for identifying information. - `label` string — Custom field name. - `value` string — Custom field value. - `shown` boolean — Show custom field on report PDF. - `loan` ClientVerificationLoan — Optional loan details for regular payroll and mortgage verification workflows. - `number` string — Loan number or identifier. - `borrower_id` string — Borrower identifier. - `application_id` string — Application identifier. - `officer_email` string — Email of the loan officer requesting the verification. - `billing` ClientVerificationBilling — Optional billing details for regular payroll and mortgage verification workflows. - `cost_center` string — Cost center identifier. ## Response `200` - ClientVerification - `id` string, uuid — Unique ID of the verification. - `user` string, uuid — ID of the user associated with the verification. - `created_at` string, date-time — Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the verification was requested. - `updated_at` string, date-time — Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the verification object was last updated. - `channel` 'api' | 'encompass' — Origin of the verification order. - `status` ClientVerificationStatus — Verification status information. - `state` 'PENDING' | 'PROCESSING' | 'PAUSED' | 'CANCELLED' | 'COMPLETED' — Verification state. - `PENDING` - Initial status after verification is created. - `PROCESSING` - Verification processing is underway. - `PAUSED` - Verification is paused because more data or documents are required. - `CANCELLED` - Verification has been cancelled. - `COMPLETED` - Verification is complete and report assets are available. - `code` 'pending' | 'documents_processing' | 'more_data_required' | 'report_available' | 'waiting_on_third_party' | 'report_generating' | 'argyle_timeout' | 'cancelled_by_client' | 'completed' | 'completed_with_errors' | 'user_session_started' | 'authenticated' | 'awaiting_certification' — Verification status code. For `doc-voi-mortgage` report types: - `pending` - Verification created. - `documents_processing` - Documents processing. - `more_data_required` - More data or documents are needed to complete the verification. - `report_available` - Data and documents are sufficient to complete verification. - `waiting_on_third_party` - Awaiting processing by a third party. - `report_generating` - Report is currently generating. - `argyle_timeout` - Verification request has been cancelled by Argyle after 180 days of inactivity. - `cancelled_by_client` - Verification has been cancelled. - `completed` - Verification request complete. Report can be retrieved. - `completed_with_errors` - Verification request completed. Report can be retrieved but is not GSE eligible. For payroll, government, and banking report types: - `pending` - Verification created. - `user_session_started` - User opened the payroll or banking connection experience. - `authenticated` - User authenticated for payroll or banking; data aggregation is in progress. - `awaiting_certification` - awaiting user certification for aggregated government data - `completed` - Report is ready for download. - `errors` ClientVerificationError[] — Error information. Error details can explain what caused a `PAUSED` state or prevented GSE eligibility for a `COMPLETED` document verification. - `code` string — Error code. - `title` string — Error title. - `message` string — Error message. - `resources` ClientVerificationErrorResource[] — Additional troubleshooting resources (for example, the ID of an unmatched document). - `id` string, nullable — ID of the associated resource, if available. - `type` string — Resource type. - `name` string — Resource name. - `report` ClientVerificationReport — Report information. - `id` string, uuid, nullable — Unique ID of the report. Only available when verification state is `COMPLETED`. - `type` 'voie' | 'voe' | 'voie-government' | 'voa' | 'voi' | 'voai' | 'voe-transactions' | 'doc-voi-mortgage' — The type of report. Payroll: - `voie` - Verification of Income and Employment. - `voe` - Verification of Employment. - `voie-government` - Government income verification. Banking: - `voa` - Banking verification of assets. - `voi` - Banking verification of income. - `voai` - Banking verification of income and assets. - `voe-transactions` - Banking verification of employment. Documents: - `doc-voi-mortgage` - Mortgage document-based verification of income, integrated with Freddie Mac's AIM Check. - `self_certification` boolean, nullable — For `voie-government` reports, indicates whether the applicant self-certification flow is enabled in Link. Defaults to `true` for `voie-government` reports and `null` for other report types. - `file_url` string, nullable — Download link to the report PDF. Requires [Argyle authentication headers](/api-guide/overview#authentication). Only available when verification state is `COMPLETED`. - `json_url` string, nullable — Download link to the report in JSON. Requires [Argyle authentication headers](/api-guide/overview#authentication). Only available when verification state is `COMPLETED`. - `configuration` ClientVerificationReportConfiguration — Optional banking report configurations. - `bank_accounts` string[] — List of [bank account](/api-reference/bank-accounts) IDs to be included in the report. - `from_date` string, date-time — Restrict report to data from on or after this datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - `VOAI` reports - controls the length of asset history - `VOA` reports - controls the length of asset history - `VOI` reports - controls the length of income history - `income_from_date` string, date-time — Restrict report to data from on or after this datetime ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - `VOAI` reports - controls the length of income history - Does not apply to `VOA` or `VOI` reports. - `income_stream_confidence_minimum` integer — Limit income streams used in the report to those above this confidence value (`0-100` accepted). Only available for `VOI` and `VOAI` report types. - `report_custom_fields` ClientReportCustomField[] — Include up to `5` custom objects in the report metadata. Often used for identifying information. - `label` string — Custom field name. - `value` string — Custom field value. - `shown` boolean — Show custom field on report PDF. - `employments` ClientVerificationEmployment[] — List of employments for the user. Documents only. - `employer` string — Name of the employer. - `status` 'active' | 'previous' — User's current employment status at this employer. - `hire_date` string, date — Employment start date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. - `termination_date` string, date, nullable — Employment end date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` when employment `status` is `active`. - `loan` ClientVerificationLoan — Optional loan details for regular payroll and mortgage verification workflows. - `number` string — Loan number or identifier. - `borrower_id` string — Borrower identifier. - `application_id` string — Application identifier. - `officer_email` string — Email of the loan officer requesting the verification. - `billing` ClientVerificationBilling — Optional billing details for regular payroll and mortgage verification workflows. - `cost_center` string — Cost center identifier. - `data_source` 'payroll' | 'banking' | 'documents' — Source of verification data. --- [API](https://skmtc.dev/argyle/apis/users-api.md) · [All operations](https://skmtc.dev/argyle/apis/users-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argyle/users-api/revisions/73a1a5c56823/schema)