openapi: 3.0.0
info:
  title: Verifications API
  version: 1.0.0
  description: |
    Order payroll, banking, and document-based income verifications.
security:
  - basicAuth: []
paths:
  /v2/sessions:
    post:
      summary: Create a session
      description: >-
        Create a connection session and return a `link` URL that launches the
        frontend experience.


        Session links expire after one hour. A new session link can be created
        at any time by creating another session for the active verification.


        <Note>This endpoint is for payroll and banking verifications
        only.</Note>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientSessionCreateRequest'
            examples:
              payroll:
                summary: Example Request (Payroll)
                value:
                  verification: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                  configuration:
                    redirect_url: https://your-application.com/return
                    flow_id: 12ABCD3E
                    items:
                      - item_000000001
                      - item_000000002
                    language: EN
                    mobile_app: true
              banking:
                summary: Example Request (Banking)
                value:
                  verification: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                  configuration:
                    experience: 97f1eccb-241d-4052-8409-fab9e27a589b
                    single_use_url: false
                    redirect_url: https://your-application.com/return
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSession'
              examples:
                payroll:
                  summary: Example Response (Payroll)
                  value:
                    verification: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                    configuration:
                      experience: null
                      single_use_url: false
                      redirect_url: https://your-application.com/return
                      flow_id: 12ABCD3E
                      items:
                        - item_000000001
                        - item_000000002
                      language: EN
                      mobile_app: true
                    link: https://connect.argyle.com/?...
                    data_source: payroll
                banking:
                  summary: Example Response (Banking)
                  value:
                    verification: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                    configuration:
                      experience: 97f1eccb-241d-4052-8409-fab9e27a589b
                      single_use_url: false
                      redirect_url: https://your-application.com/return
                    link: https://connect2.finicity.com?...
                    data_source: banking
  /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: &ref_0
                    number: '1234'
                    borrower_id: ABC789
                    application_id: '2121313'
                    officer_email: john.doe@mortgage.com
                  billing: &ref_1
                    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: *ref_0
                  billing: *ref_1
              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: *ref_0
                  billing: *ref_1
      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: *ref_0
                    billing: *ref_1
                    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: *ref_0
                    billing: *ref_1
                    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: *ref_0
                    billing: *ref_1
                    data_source: documents
    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
  /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: *ref_0
                  billing: *ref_1
              banking:
                summary: Example Request (Banking)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: voa
                    configuration:
                      from_date: '2025-01-01T00:00:00Z'
                  loan: *ref_0
                  billing: *ref_1
              documents:
                summary: Example Request (Documents)
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  report:
                    type: doc-voi-mortgage
                  loan: *ref_0
                  billing: *ref_1
      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: *ref_0
                    billing: *ref_1
                    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: *ref_0
                    billing: *ref_1
                    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: *ref_0
                    billing: *ref_1
                    data_source: documents
  /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
    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
  /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
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username = api_key_id, Password = api_key_secret
  schemas:
    ClientCreateUserResponse:
      type: object
      description: Response returned after creating a client user.
      properties:
        user_token:
          type: string
          description: Token associated with the created user.
        id:
          type: string
          format: uuid
          description: Unique ID of the user.
    ClientAddress:
      type: object
      description: Address of the user.
      properties:
        city:
          type: string
          description: Name of the city, town, district, or similar regional entity.
        line1:
          type: string
          description: Address-Line 1, usually street address or P.O. Box information.
        line2:
          type: string
          nullable: true
          description: Address-Line 2, usually the apartment or unit number.
        state:
          type: string
          description: State, county, province, region, or equivalent.
        country:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2 format).
        postal_code:
          type: string
          nullable: true
          description: Zip code, or equivalent.
    ClientBirthDate:
      type: object
      description: Date of birth in year-month-day format.
      properties:
        year:
          type: integer
          description: Birth year (1900 or later).
        month:
          type: integer
          description: Birth month (between 1 and 12).
        day:
          type: integer
          description: Birth day (between 1 and 31).
    ClientOpenBankingEndUser:
      type: object
      description: Contains details about the person or entity making the lending decision.
      properties:
        name:
          type: string
          description: Name of the lender or entity.
        address:
          type: string
          description: >-
            Street address or P.O. Box information (include apartment or unit
            numbers).
        city:
          type: string
          description: Name of the city, town, district, or similar regional entity.
        state:
          type: string
          description: State, county, province, region, or equivalent.
        zip:
          type: string
          description: Zip code, or equivalent.
        phone:
          type: string
          description: Phone number of the lender or entity.
    ClientOpenBanking:
      type: object
      description: Banking-specific user metadata.
      properties:
        end_user:
          $ref: '#/components/schemas/ClientOpenBankingEndUser'
    ClientUserCreateRequest:
      type: object
      description: >
        Request body for creating a client user.


        This matches the public `/v2/users` request shape.


        `external_metadata.suppress_verification = true` is recommended when
        manually orchestrating banking and document verification flows.
      properties:
        first_name:
          type: string
          description: User first name.
        last_name:
          type: string
          description: User last name.
        email:
          type: string
          description: User email address.
        phone_number:
          type: string
          description: User phone number. E.164 international format recommended.
        ssn:
          type: string
          description: User Social Security number.
        address:
          $ref: '#/components/schemas/ClientAddress'
        birth_date:
          $ref: '#/components/schemas/ClientBirthDate'
        external_metadata:
          type: object
          description: Additional metadata for internal workflows.
          additionalProperties: true
        open_banking:
          $ref: '#/components/schemas/ClientOpenBanking'
        external_id:
          type: string
          nullable: true
          description: External identifier for your internal mapping.
    ClientUserUpdateRequest:
      type: object
      description: Request body for updating a client user.
      properties:
        first_name:
          type: string
          description: User first name.
        last_name:
          type: string
          description: User last name.
        email:
          type: string
          description: User email address.
        phone_number:
          type: string
          description: User phone number.
        ssn:
          type: string
          description: User Social Security number.
        address:
          $ref: '#/components/schemas/ClientAddress'
        birth_date:
          $ref: '#/components/schemas/ClientBirthDate'
        external_metadata:
          type: object
          description: Additional metadata for internal workflows.
          additionalProperties: true
        open_banking:
          $ref: '#/components/schemas/ClientOpenBanking'
        external_id:
          type: string
          nullable: true
          description: External identifier for your internal mapping.
    ClientUser:
      type: object
      description: Client user object.
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the user.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when
            the user was created.
        items_connected:
          type: array
          items:
            type: string
          description: Items the user has connected through Link.
        employers_connected:
          type: array
          items:
            type: string
          description: Employers associated with the connected items.
        first_name:
          type: string
          description: User first name.
        last_name:
          type: string
          description: User last name.
        email:
          type: string
          description: User email address.
        phone_number:
          type: string
          description: User phone number.
        ssn:
          type: string
          description: User Social Security number.
        address:
          $ref: '#/components/schemas/ClientAddress'
        birth_date:
          $ref: '#/components/schemas/ClientBirthDate'
        external_metadata:
          type: object
          description: Additional metadata for internal workflows.
          additionalProperties: true
        external_id:
          type: string
          nullable: true
          description: External identifier for your internal mapping.
    ClientSessionCreateConfiguration:
      type: object
      description: Connection session configuration for payroll and banking verifications.
      properties:
        experience:
          type: string
          format: uuid
          description: Banking only. Optional bank connection experience customization ID.
        single_use_url:
          type: boolean
          description: >-
            Banking only. If `true`, the session link expires after one
            successful connection.
        redirect_url:
          type: string
          nullable: true
          description: >-
            Payroll and banking. Optional redirect URL after session completion.
            Hosted/direct-launch flows should always set this. On desktop
            browsers, use a regular `https://` URL. For mobile app flows, use a
            custom scheme such as `your-custom-scheme://return-to-app`, or a
            Universal Link on iOS / App Link on Android. Universal Links and App
            Links are the more modern approach. You can include an
            application-owned state or nonce value to match the returning
            browser session to an internal user, session, or verification.
            Argyle appends `user_submission_complete` and
            `user_attempted_employer_selection`, which mirror the
            [`onClose`](/link/reference/callbacks#onclose) fields.
        flow_id:
          type: string
          description: >-
            Payroll only. Optional payroll embedded connection experience
            customization ID.
        items:
          type: array
          description: >-
            Payroll only. Limits Link to the provided Items. If one Item is
            provided, Link skips search and opens that Item's login screen. If
            multiple Items are provided, Link shows only those Items.
          items:
            type: string
          example:
            - item_000000001
            - item_000000002
        language:
          type: string
          enum:
            - EN
            - ES
            - RU
            - ZH
          description: >-
            Payroll only. Supported Link [display
            language](/link/initialization/overview#optional-initialization-parameters).
        mobile_app:
          type: boolean
          description: >-
            Payroll only. Set to `true` when the session is used in a mobile
            app, including Hosted Link opened in a secure browser context.
    ClientSessionConfiguration:
      allOf:
        - $ref: '#/components/schemas/ClientSessionCreateConfiguration'
    ClientSessionCreateRequest:
      type: object
      properties:
        verification:
          type: string
          format: uuid
          description: ID of the verification used to initialize the session.
        configuration:
          $ref: '#/components/schemas/ClientSessionCreateConfiguration'
      required:
        - verification
    ClientSession:
      type: object
      description: Client connection session object.
      properties:
        verification:
          type: string
          format: uuid
          description: Verification ID associated with the session.
        configuration:
          $ref: '#/components/schemas/ClientSessionConfiguration'
        link:
          type: string
          description: >-
            URL used to launch the payroll or banking frontend experience. For
            payroll, use it as `connectUrl` when initializing the [Web
            SDK](/link/initialization/web#initialize-with-connecturl); the
            returned session URL already determines whether the session runs in
            Sandbox or Production. Alternatively, open it directly for [Hosted
            Link](/link/initialization/hosted-link). For banking, use it to
            launch either an Embedded banking session or a Hosted banking
            session. Session links expire after one hour. A new session link can
            be created at any time by creating another session for the active
            verification.
        data_source:
          type: string
          enum:
            - payroll
            - banking
          description: Source of connection data.
    ClientVerificationListResponse:
      type: object
      description: Paginated list of client verification objects.
      properties:
        next:
          type: string
          format: uri
          nullable: true
          description: URL for the next page of results, if available.
        previous:
          type: string
          format: uri
          nullable: true
          description: URL for the previous page of results, if available.
        results:
          type: array
          items:
            $ref: '#/components/schemas/ClientVerification'
    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.
    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'
    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
    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.
    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'
    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: &ref_2
            - 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` - 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`.
    ClientVerificationEmploymentRequest:
      allOf:
        - $ref: '#/components/schemas/ClientVerificationEmployment'
        - type: object
          required:
            - employer
            - status
            - hire_date
    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.
    ClientVerificationCreateReportRequest:
      type: object
      description: Report request configuration.
      properties:
        type:
          type: string
          enum: *ref_2
          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 verification of income.

            - `voai` - Banking verification of income and assets.

            - `voe-transactions` - Banking verification of employment.


            Documents:

            - `doc-voi-mortgage` - Document-based verification of income,
            integrated with Freddie Mac's AIM Check.
        configuration:
          allOf:
            - $ref: '#/components/schemas/ClientVerificationReportConfiguration'
            - description: Optional banking report configurations.
      required:
        - type
    ClientVerificationRefreshReportRequest:
      type: object
      description: Report request configuration for refresh requests.
      properties:
        type:
          type: string
          enum:
            - voie
            - voe
            - voa
            - voi
            - voai
            - voe-transactions
            - doc-voi-mortgage
          description: >-
            Payroll, banking, or Doc VOI report type to generate.


            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` - Document-based verification of income,
            integrated with Freddie Mac's AIM Check.
        configuration:
          allOf:
            - $ref: '#/components/schemas/ClientVerificationReportConfiguration'
            - description: Optional banking report configurations.
      required:
        - type
    ClientVerificationCreateRequest:
      type: object
      description: |-
        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.
      properties:
        user:
          type: string
          format: uuid
          description: User ID for the verification.
        employments:
          type: array
          description: >-
            List of employments for the user.


            Required for document verifications only. Not used for payroll or
            banking verifications.
          items:
            $ref: '#/components/schemas/ClientVerificationEmploymentRequest'
        report:
          $ref: '#/components/schemas/ClientVerificationCreateReportRequest'
        loan:
          $ref: '#/components/schemas/ClientVerificationLoan'
        billing:
          $ref: '#/components/schemas/ClientVerificationBilling'
      required:
        - user
        - report
    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
    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'