Argyle Partners API

openapi: 3.0.0
info:
  title: Argyle API Accounts Partners API
  version: '2.0'
  description: Accounts are payroll connections made through Link.
security:
- basicAuth: []
tags:
- name: Partners
paths:
  /partners/v2/users:
    post:
      summary: Create a user
      description: Creates a new user object for partner verification workflows.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUserCreateRequest'
            example:
              client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
              first_name: Jane
              last_name: Doe
              ssn: 000-00-0000
              email: jane@example.com
              phone_number: '+15555555555'
              address:
                city: New York
                line1: 123 Main St
                line2: null
                state: NY
                country: US
                postal_code: null
              birth_date:
                year: 1990
                month: 1
                day: 13
              external_id: null
              external_metadata:
                suppress_verification: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCreateUserResponse'
              example:
                user_token: <SECRET>
                id: 7a614711-066f-4b6b-b319-4c6236b5acc1
      tags:
      - Partners
  /partners/v2/users/{id}:
    patch:
      summary: Update a user
      description: Updates a user object.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the user object to be updated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUserUpdateRequest'
            example:
              email: jane@example.com
              phone_number: '+15555555555'
              external_id: ABC
              external_metadata:
                suppress_verification: true
                additional_id: '123'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerUser'
              example:
                id: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                created_at: '2023-03-09T04:54:35.170468Z'
                items_connected:
                - item_123456789
                - item_987654321
                employers_connected:
                - Whole Goods
                - Bullseye
                first_name: Jane
                last_name: Doe
                ssn: 000-00-0000
                email: jane@example.com
                phone_number: '+15555555555'
                address:
                  city: New York
                  line1: 123 Main St
                  line2: null
                  state: NY
                  country: US
                  postal_code: null
                birth_date:
                  year: 1990
                  month: 1
                  day: 13
                external_metadata:
                  suppress_verification: true
                  additional_id: '123'
                external_id: ABC
      tags:
      - Partners
  /partners/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/PartnerSessionCreateRequest'
            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/PartnerSession'
              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
      tags:
      - Partners
  /partners/v2/verifications:
    post:
      summary: Order a verification
      description: 'Orders a new verification.


        <Note>

        [Create a user](/api-reference/verifications-partners-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/PartnerVerificationCreateRequest'
            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/PartnerVerification'
              examples:
                payroll:
                  summary: Example Response (Payroll)
                  value:
                    id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                    user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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:
      - Partners
    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/PartnerVerification'
              example:
                next: https://api-sandbox.argyle.com/partners/v2/verifications?cursor=ZXhhbXBsZV9jdXJzb3I
                previous: null
                results:
                - id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                  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
                  client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                  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:
      - Partners
  /partners/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/PartnerVerificationRefreshRequest'
            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/PartnerVerification'
              examples:
                payroll:
                  summary: Example Response (Payroll)
                  value:
                    id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                    user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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:
      - Partners
  /partners/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/PartnerVerification'
              example:
                id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                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:
      - Partners
    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/PartnerVerificationUpdateRequest'
            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/PartnerVerification'
              examples:
                payroll:
                  summary: Example Response (Payroll)
                  value:
                    id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                    user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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
                    client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                    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:
      - Partners
  /partners/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/PartnerVerification'
              example:
                id: 43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b
                user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                client: 39096494-45c8-4fd8-9454-3d1cb2d62db7
                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:
      - Partners
  /partners/v2/user-uploads:
    post:
      summary: Upload a document
      description: Upload a document via the API.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - user
              - document_type
              - upload
              properties:
                user:
                  type: string
                  format: uuid
                  description: ID of the user object.
                document_type:
                  type: string
                  enum:
                  - paystubs
                  - W-2
                  - 1099
                  - proof-of-identity
                  - proof-of-address
                  - miscellaneous
                  description: The type of document.
                upload:
                  type: string
                  format: bina

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