Argyle Verifications API

openapi: 3.0.0
info:
  title: Argyle Accounts Verifications API
  version: '2.0'
  description: RESTful API providing user-consented access to payroll and employment data including identities, paystubs, gigs, shifts, vehicles, ratings, payroll documents, and deposit destinations across thousands of employers and gig platforms.
  contact:
    name: Argyle Support
    url: https://docs.argyle.com/
  x-api-id: argyle
  x-audience: public
servers:
- url: https://api.argyle.com
  description: Production
- url: https://api-sandbox.argyle.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Verifications
paths:
  /v2/verifications:
    post:
      summary: Order a verification
      description: 'Orders a new verification.


        <Note>

        [Create a user](/api-reference/verifications-guide#create-a-user) or update an existing user with the required details before ordering payroll, banking, or document verifications.

        </Note>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientVerificationCreateRequest'
            examples:
              payroll:
                summary: Example Request (Payroll)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: voie
                  loan: &id001
                    number: '1234'
                    borrower_id: ABC789
                    application_id: '2121313'
                    officer_email: john.doe@mortgage.com
                  billing: &id002
                    cost_center: '5'
              banking:
                summary: Example Request (Banking)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: voai
                    configuration:
                      from_date: '2024-01-01T00:00:00Z'
                      income_stream_confidence_minimum: 50
                      report_custom_fields:
                      - label: loanID
                        value: '12345'
                        shown: true
                  loan: *id001
                  billing: *id002
              documents:
                summary: Example Request (Documents)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  employments:
                  - employer: Warehouse Services Inc
                    status: active
                    hire_date: '2023-02-01'
                    termination_date: null
                  report:
                    type: doc-voi-mortgage
                  loan: *id001
                  billing: *id002
      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: PENDING
                      code: pending
                      errors: []
                    report:
                      id: null
                      type: voie
                      file_url: null
                      json_url: null
                    employments: []
                    loan: *id001
                    billing: *id002
                    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: PENDING
                      code: pending
                      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: *id001
                    billing: *id002
                    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: PENDING
                      code: pending
                      errors: []
                    report:
                      id: null
                      type: doc-voi-mortgage
                      file_url: null
                      json_url: null
                    employments:
                    - employer: Warehouse Services Inc
                      status: active
                      hire_date: '2023-02-01'
                      termination_date: null
                    loan: *id001
                    billing: *id002
                    data_source: documents
      tags:
      - Verifications
    get:
      summary: List all verifications
      description: Returns a paginated list of all verification objects.
      parameters:
      - name: user
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Filter by user ID.
      - name: status_state
        in: query
        required: false
        schema:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - PAUSED
          - CANCELLED
          - COMPLETED
        description: Filter by verification status `state`.
      - name: status_code
        in: query
        required: false
        schema:
          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: Filter by verification status `code`.
      - name: report_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - voie
          - voe
          - voa
          - voi
          - voai
          - voe-transactions
          - doc-voi-mortgage
        description: Filter by report `type`.
      - name: loan_number
        in: query
        required: false
        schema:
          type: string
        description: Filter by loan `number`.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 'Number of verification objects returned [per page](/api-guide/overview#pagination). Default: 10. Maximum: 200.

          '
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The URL returned in `next` or `previous` used to retrieve another [page](/api-guide/overview#pagination) of results.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: URL for the next page of results, if available.
                  previous:
                    type: string
                    nullable: true
                    description: URL for the previous page of results, if available.
                  results:
                    type: array
                    description: Array of verification objects.
                    items:
                      $ref: '#/components/schemas/ClientVerification'
              example:
                next: https://api-sandbox.argyle.com/v2/verifications?cursor=ZXhhbXBsZV9jdXJzb3I
                previous: null
                results:
                - 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: PENDING
                    code: pending
                    errors: []
                  report:
                    id: 2a14ce6f-3aed-4c15-8ea2-92a17b6edb95
                    type: voie
                    file_url: null
                    json_url: null
                  employments: []
                  loan:
                    number: '1234'
                    borrower_id: ABC789
                    application_id: '2121313'
                    officer_email: john.doe@mortgage.com
                  billing:
                    cost_center: '5'
                  data_source: payroll
                - id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc3333
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9345
                  created_at: '2023-03-10T05:14:06.081Z'
                  updated_at: '2023-03-10T13:03: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: '1234'
                    borrower_id: ABC789
                    application_id: '2121313'
                    officer_email: john.doe@mortgage.com
                  billing:
                    cost_center: '5'
                  data_source: banking
      tags:
      - Verifications
  /v2/verifications/refresh:
    post:
      summary: Refresh a verification
      description: 'Creates a new payroll, banking, or Doc VOI verification without requiring the user to reconnect or upload additional documents.


        For payroll and banking, a valid connection must already exist. For Doc VOI, the new report is generated from the user''s existing uploaded documents.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientVerificationRefreshRequest'
            examples:
              payroll:
                summary: Example Request (Payroll)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: voie
                  loan: &id003
                    number: '1234'
                    borrower_id: ABC789
                    application_id: '2121313'
                    officer_email: john.doe@mortgage.com
                  billing: &id004
                    cost_center: '5'
              banking:
                summary: Example Request (Banking)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: voa
                    configuration:
                      from_date: '2025-01-01T00:00:00Z'
                  loan: *id003
                  billing: *id004
              documents:
                summary: Example Request (Documents)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: doc-voi-mortgage
                  loan: *id003
                  billing: *id004
      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: PENDING
                      code: pending
                      errors: []
                    report:
                      id: null
                      type: voie
                      file_url: null
                      json_url: null
                    employments: []
                    loan: *id003
                    billing: *id004
                    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: PENDING
                      code: pending
                      errors: []
                    report:
                      id: null
                      type: voa
                      file_url: null
                      json_url: null
                      configuration:
                        from_date: '2025-01-01T00:00:00Z'
                    employments: []
                    loan: *id003
                    billing: *id004
                    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: PENDING
                      code: pending
                      errors: []
                    report:
                      id: null
                      type: doc-voi-mortgage
                      file_url: null
                      json_url: null
                    employments: []
                    loan: *id003
                    billing: *id004
                    data_source: documents
      tags:
      - Verifications
  /v2/verifications/{id}:
    get:
      summary: Retrieve a verification
      description: Retrieves a verification.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the verification to be retrieved.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientVerification'
              example:
                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: '1234'
                  borrower_id: ABC789
                  application_id: '2121313'
                  officer_email: john.doe@mortgage.com
                billing:
                  cost_center: '5'
                data_source: banking
      tags:
      - Verifications
    patch:
      summary: Update a verification
      description: 'Updates verification metadata or employments.


        <Note>

        After a verification is updated, it will re-enter the `PROCESSING` state.

        </Note>

        '
      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
      tags:
      - Verifications
  /v2/verifications/{id}/cancel:
    post:
      summary: Cancel a verification
      description: 'Cancels a verification order.


        <Note>

        Only verifications in the `PAUSED` state can be cancelled.

        </Note>

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the verification to be cancelled.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientVerification'
              example:
                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: CANCELLED
                  code: cancelled_by_client
                  errors: []
                report:
                  id: null
                  type: doc-voi-mortgage
                  file_url: null
                  json_url: null
                employments:
                - employer: Warehouse Services Inc
                  status: active
                  hire_date: '2023-02-01'
                  termination_date: null
                loan:
                  number: '1234'
                  borrower_id: ABC789
                  application_id: '2121313'
                  officer_email: john.doe@mortgage.com
                billing:
                  cost_center: '5'
                data_source: documents
      tags:
      - Verifications
components:
  schemas:
    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
    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'
    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.
    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.
    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.
    ClientVerificationRefreshRequest:
      type: object
      properties:
        user:
          type: string
          format: uuid
          description: User ID for the verification refresh.
        report:
          $ref: '#/components/schemas/ClientVerificationRefreshReportRequest'
        loan:
          $ref: '#/components/schemas/ClientVerificationLoan'
        billing:
          $ref: '#/components/schemas/ClientVerificationBilling'
      required:
      - user
      - report
    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'
    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
    ClientVerificationCreateReportRequest:
      type: object
      description: Report request configuration.
      properties:
        type:
          type: string
          enum:
          - voie
          - voe
          - voa
          - voi
          - voai
          - voe-transactions
          - doc-voi-mortgage
          description: 'The type of report to generate.


            Payroll:

            - `voie` - Verification of Income and Employment.

            - `voe` - Verification of Employment.


            Banking:

            - `voa` - Banking verification of assets.

            - `voi` - Banking 

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/argyle/refs/heads/main/openapi/argyle-verifications-api-openapi.yml