> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a verification
> Updates verification metadata or employments.
After a verification is updated, it will re-enter the `PROCESSING` state.
## OpenAPI
````yaml openAPI/verifications.yaml patch /v2/verifications/{id}
openapi: 3.0.0
info:
title: Verifications API
version: 1.0.0
description: |
Order payroll, banking, and document-based income verifications.
servers: []
security:
- basicAuth: []
paths:
/v2/verifications/{id}:
patch:
summary: Update a verification
description: >
Updates verification metadata or employments.
After a verification is updated, it will re-enter the `PROCESSING`
state.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the verification to be updated.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClientVerificationUpdateRequest'
examples:
payroll:
summary: Example Request (Payroll)
value:
loan:
number: '5678'
borrower_id: '5678'
application_id: '2121313'
officer_email: john.doe@mortgage.com
billing:
cost_center: new_cost_center
banking:
summary: Example Request (Banking)
value:
loan:
number: '5678'
borrower_id: '5678'
application_id: '2121313'
officer_email: john.doe@mortgage.com
billing:
cost_center: new_cost_center
documents:
summary: Example Request (Documents)
value:
employments:
- employer: Warehouse Services Inc
status: previous
hire_date: '2015-08-28'
termination_date: '2023-05-01'
- employer: Amazon
status: active
hire_date: '2023-06-15'
termination_date: null
loan:
borrower_id: '5678'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ClientVerification'
examples:
payroll:
summary: Example Response (Payroll)
value:
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: PROCESSING
code: authenticated
errors: []
report:
id: null
type: voie
file_url: null
json_url: null
employments: []
loan:
number: '5678'
borrower_id: '5678'
application_id: '2121313'
officer_email: john.doe@mortgage.com
billing:
cost_center: new_cost_center
data_source: payroll
banking:
summary: Example Response (Banking)
value:
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: PROCESSING
code: authenticated
errors: []
report:
id: null
type: voai
file_url: null
json_url: null
configuration:
from_date: '2024-01-01T00:00:00Z'
income_stream_confidence_minimum: 50
report_custom_fields:
- label: loanID
value: '12345'
shown: true
employments: []
loan:
number: '5678'
borrower_id: '5678'
application_id: '2121313'
officer_email: john.doe@mortgage.com
billing:
cost_center: new_cost_center
data_source: banking
documents:
summary: Example Response (Documents)
value:
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: PROCESSING
code: documents_processing
errors: []
report:
id: null
type: doc-voi-mortgage
file_url: null
json_url: null
employments:
- employer: Warehouse Services Inc
status: previous
hire_date: '2015-08-28'
termination_date: '2023-05-01'
- employer: Amazon
status: active
hire_date: '2023-06-15'
termination_date: null
loan:
number: '1234'
borrower_id: '5678'
application_id: '2121313'
officer_email: john.doe@mortgage.com
billing:
cost_center: '5'
data_source: documents
components:
schemas:
ClientVerificationUpdateRequest:
type: object
description: >
Request body for updating a verification.
- `loan` and `billing` can be updated for either data source.
- `employments` can only be updated when a document verification is in
the `PAUSED` state.
- Updating `employments` replaces the full employments array.
properties:
loan:
$ref: '#/components/schemas/ClientVerificationLoan'
billing:
$ref: '#/components/schemas/ClientVerificationBilling'
employments:
type: array
description: Updated list of employments for the user.
items:
$ref: '#/components/schemas/ClientVerificationEmploymentRequest'
ClientVerification:
type: object
properties:
id:
type: string
format: uuid
description: Unique ID of the verification.
user:
type: string
format: uuid
description: ID of the user associated with the verification.
created_at:
type: string
format: date-time
description: >-
Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when
the verification was requested.
updated_at:
type: string
format: date-time
description: >-
Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when
the verification object was last updated.
channel:
type: string
enum:
- api
- encompass
example: api
description: Origin of the verification order.
status:
$ref: '#/components/schemas/ClientVerificationStatus'
report:
$ref: '#/components/schemas/ClientVerificationReport'
employments:
type: array
description: List of employments for the user. Documents only.
items:
$ref: '#/components/schemas/ClientVerificationEmployment'
loan:
$ref: '#/components/schemas/ClientVerificationLoan'
billing:
$ref: '#/components/schemas/ClientVerificationBilling'
data_source:
type: string
enum:
- payroll
- banking
- documents
description: Source of verification data.
ClientVerificationLoan:
type: object
description: Optional loan details.
properties:
number:
type: string
description: Loan number or identifier.
borrower_id:
type: string
description: Borrower identifier.
application_id:
type: string
description: Application identifier.
officer_email:
type: string
description: Email of the loan officer requesting the verification.
ClientVerificationBilling:
type: object
description: Optional billing details.
properties:
cost_center:
type: string
description: Cost center identifier.
ClientVerificationEmploymentRequest:
allOf:
- $ref: '#/components/schemas/ClientVerificationEmployment'
- type: object
required:
- employer
- status
- hire_date
ClientVerificationStatus:
type: object
description: Verification status information.
properties:
state:
type: string
enum:
- PENDING
- PROCESSING
- PAUSED
- CANCELLED
- COMPLETED
description: >
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:
type: string
enum:
- 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
description: >-
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 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.
- `completed` - Report is ready for download.
errors:
type: array
description: >
Error information.
Error details can explain what caused a `PAUSED` state or prevented
GSE eligibility for a `COMPLETED` document verification.
items:
$ref: '#/components/schemas/ClientVerificationError'
ClientVerificationReport:
type: object
description: Report information.
properties:
id:
type: string
format: uuid
nullable: true
description: |
Unique ID of the report.
Only available when verification state is `COMPLETED`.
type:
type: string
enum:
- voie
- voe
- voa
- voi
- voai
- voe-transactions
- doc-voi-mortgage
description: >-
The type of report.
Payroll:
- `voie` - Verification of Income and Employment.
- `voe` - Verification of Employment.
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.
file_url:
type: string
nullable: true
example: www.argyle.com/storagename/pdf
description: >
Download link to the report PDF.
Requires [Argyle authentication
headers](/api-guide/overview#authentication). Only available when
verification state is `COMPLETED`.
json_url:
type: string
nullable: true
example: www.argyle.com/storagename/json
description: >
Download link to the report in JSON.
Requires [Argyle authentication
headers](/api-guide/overview#authentication). Only available when
verification state is `COMPLETED`.
configuration:
$ref: '#/components/schemas/ClientVerificationReportConfiguration'
ClientVerificationEmployment:
type: object
description: Employment details for the user.
properties:
employer:
type: string
description: Name of the employer.
status:
type: string
enum:
- active
- previous
description: User's current employment status at this employer.
hire_date:
type: string
format: date
description: >-
Employment start date in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
termination_date:
type: string
format: date
nullable: true
description: >-
Employment end date in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format. `null` when
employment `status` is `active`.
ClientVerificationError:
type: object
description: Verification error details.
properties:
code:
type: string
description: Error code.
title:
type: string
description: Error title.
message:
type: string
description: Error message.
resources:
type: array
description: >-
Additional troubleshooting resources (for example, the ID of an
unmatched document).
items:
$ref: '#/components/schemas/ClientVerificationErrorResource'
example:
code: self-employed_income
title: Self-employed income
message: Self-employed income cannot be assessed using Paystub and W2 Data.
resources:
- id: null
type: employments
name: Freelance Consulting LLC
ClientVerificationReportConfiguration:
type: object
description: Optional banking report configurations.
properties:
bank_accounts:
type: array
items:
type: string
description: >-
List of [bank account](/api-reference/bank-accounts) IDs to be
included in the report.
from_date:
type: string
format: date-time
description: >
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:
type: string
format: date-time
description: >
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:
type: integer
minimum: 0
maximum: 100
description: >
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:
type: array
maxItems: 5
description: >-
Include up to `5` custom objects in the report metadata. Often used
for identifying information.
items:
$ref: '#/components/schemas/ClientReportCustomField'
ClientVerificationErrorResource:
type: object
description: Verification error resource details.
properties:
id:
type: string
nullable: true
description: ID of the associated resource, if available.
type:
type: string
description: Resource type.
name:
type: string
description: Resource name.
ClientReportCustomField:
type: object
description: Custom field returned in report JSON as a pass-through value.
properties:
label:
type: string
description: Custom field name.
value:
type: string
description: Custom field value.
shown:
type: boolean
description: Show custom field on report PDF.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Username = api_key_id, Password = api_key_secret
````