openapi: 3.2.0
info:
  title: Argyle Sessions API
  description: Argyle OpenAPI spec
  version: 1.0.111
servers:
- url: https://api-sandbox.argyle.com/v2
  description: Sandbox
- url: https://api.argyle.com/v2
  description: Production
security:
- basicAuth: []
tags:
- name: Sessions
paths:
  /sessions:
    post:
      summary: Create a session
      description: 'Create a connection session or send an invite.


        - For an embedded session, provide `verification`. The response returns a `link` to launch or embed the frontend experience. The `link` expires after one hour.


        - For an invite, first create the user and at least one active verification. Set `type` to `invite`, provide `user`, and include `configuration.email`, `configuration.phone_number`, or both. The invite link expires after 180 days or when revoked.


        This endpoint is for payroll and banking verifications only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientSessionCreateRequest'
            examples:
              Embedded - Payroll:
                summary: Embedded - 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
              Embedded - Banking:
                summary: Embedded - 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
              Invites:
                summary: Invites
                value:
                  user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                  type: invite
                  configuration:
                    flow_id: 7B18UYWH
                    items: []
                    reply_to: hello@argyle.com
                    email: jane@example.com
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ClientSession'
                - $ref: '#/components/schemas/ClientInviteSession'
              examples:
                Embedded - Payroll:
                  summary: Embedded - 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
                Embedded - Banking:
                  summary: Embedded - 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
                Invites:
                  summary: Invites
                  value:
                    id: c188bce4-8a00-11f1-a41b-2ba97b79663a
                    user: 018051aa-f7a9-a0db-2f38-6cfa325e9d69
                    type: invite
                    configuration:
                      flow_id: 7B18UYWH
                      items: []
                      reply_to: hello@argyle.com
                      email: jane@example.com
                      phone_number: null
                    link: https://verify.argyle.com/connect/c188bce4-8a00-11f1-a41b-2ba97b79663a?sandbox=1
                    invite:
                      status: sent
                      deliveries:
                      - id: c1acc77e-8a00-11f1-9568-b321cb09ee53
                        method: email
                        status: sent
                        sent_at: '2026-07-27T21:18:47.000Z'
                        updated_at: '2026-07-27T21:18:47.000Z'
                      invited_at: '2026-07-27T21:18:47.000Z'
                      created_at: '2026-07-27T21:18:47.000Z'
                      updated_at: '2026-07-27T21:18:47.000Z'
      operationId: postSessions
      tags:
      - Sessions
components:
  schemas:
    ClientEmbeddedSessionCreateRequest:
      title: Embedded
      type: object
      properties:
        verification:
          type: string
          format: uuid
          description: ID of the verification used to initialize the session.
        type:
          type: string
          enum:
          - embedded
          default: embedded
          description: Session type. Defaults to `embedded` when omitted.
        configuration:
          $ref: '#/components/schemas/ClientSessionCreateConfiguration'
      required:
      - verification
    ClientInviteSession:
      title: Invites
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the [invite](/api-reference/invites).
        user:
          type: string
          format: uuid
          description: ID of the user associated with the invite.
        type:
          type: string
          enum:
          - invite
          description: Session type.
        configuration:
          $ref: '#/components/schemas/ClientInviteSessionConfiguration'
        link:
          type: string
          format: uri
          description: URL sent to the user by email or SMS.
        invite:
          $ref: '#/components/schemas/ClientInviteSessionInvite'
    ClientSession:
      title: Embedded
      type: 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, pass this value to the [banking SDK](/verifications/verification-types/banking#launch-the-banking-session) as `connectURL`. Hosted or no-SDK banking flows must be enabled by Argyle before use. 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.
    ClientInviteSessionConfiguration:
      type: object
      properties:
        flow_id:
          type: string
          description: Flow ID supplied for the invite. The resolved experience also depends on whether the flow matches the user's wholesale or retail context.
        items:
          type: array
          description: Items available in Link.
          items:
            type: string
        reply_to:
          type:
          - string
          - 'null'
          format: email
          description: Reply-To address for the invite email.
        email:
          type:
          - string
          - 'null'
          format: email
          description: Invite recipient email address.
        phone_number:
          type:
          - string
          - 'null'
          description: Invite recipient phone number.
    ClientInviteSessionCreateConfiguration:
      type: object
      properties:
        flow_id:
          type: string
          description: 'Flow ID for the invite experience. For Mortgage accounts, users with `external_metadata.broker` use wholesale flows; users without broker details use retail flows.


            If omitted, the matching default is used. A provided flow takes precedence only if it matches the wholesale or retail experience; otherwise, the matching default is used. See [Wholesale Mortgage](/verifications/wholesale-mortgage#choose-the-invite-flow).

            '
        items:
          type: array
          description: Limits Link to the provided Items.
          items:
            type: string
        reply_to:
          type: string
          format: email
          description: Reply-To address for the invite email.
        email:
          type: string
          format: email
          description: 'Invite recipient email address.


            **Note:** Required if `phone_number` is omitted.

            '
        phone_number:
          type: string
          description: 'Invite recipient phone number.


            **Note:** Required if `email` is omitted.

            '
    ClientInviteSessionInvite:
      type: object
      properties:
        status:
          type: string
          enum:
          - sent
          - initiated
          - attempted
          - completed
          - revoked
          description: 'Invite status. Use verification statuses to determine whether all verifications are complete.


            - `sent` - The invite was sent.

            - `initiated` - The user opened the invite and entered Link, but has not submitted login credentials, uploaded documents, or completed a response form.

            - `attempted` - The user submitted login credentials without connecting an account, or completed only a response form.

            - `completed` - The user connected an account or uploaded a document. Other verifications for the user may still be active.

            - `revoked` - The invite was revoked and its link can no longer be used.

            '
        deliveries:
          type: array
          description: Invite deliveries.
          items:
            $ref: '#/components/schemas/ClientInviteSessionDelivery'
        invited_at:
          type: string
          format: date-time
          description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the invite was sent.
        created_at:
          type: string
          format: date-time
          description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the invite was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the invite was last updated.
    ClientSessionCreateRequest:
      oneOf:
      - $ref: '#/components/schemas/ClientEmbeddedSessionCreateRequest'
      - $ref: '#/components/schemas/ClientInviteSessionCreateRequest'
    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
          - 'null'
          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.
    ClientInviteSessionCreateRequest:
      title: Invites
      type: object
      properties:
        user:
          type: string
          format: uuid
          description: 'User ID.


            **Note:** The user must have `first_name` and `last_name`.

            '
        type:
          type: string
          enum:
          - invite
          description: Session type.
        configuration:
          $ref: '#/components/schemas/ClientInviteSessionCreateConfiguration'
      required:
      - user
      - type
      - configuration
    ClientInviteSessionDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the [invite](/api-reference/invites).
        method:
          type: string
          enum:
          - email
          - sms
          description: Invite delivery method.
        status:
          type: string
          enum:
          - sent
          - delivered
          - undelivered
          - opened
          description: Invite delivery status.
        sent_at:
          type: string
          format: date-time
          description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the invite was sent.
        updated_at:
          type: string
          format: date-time
          description: Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the delivery status was last updated.
    ClientSessionConfiguration:
      allOf:
      - $ref: '#/components/schemas/ClientSessionCreateConfiguration'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username = api_key_id, Password = api_key_secret