---
title: "Create a session"
method: POST
path: "/v2/sessions"
---

# Create a session

`POST /v2/sessions`

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>

## Request body

- ClientSessionCreateRequest
  - `verification` string, uuid, required — ID of the verification used to initialize the session.
  - `configuration` ClientSessionCreateConfiguration — Connection session configuration for payroll and banking verifications.
    - `experience` string, uuid — Banking only. Optional bank connection experience customization ID.
    - `single_use_url` boolean — Banking only. If `true`, the session link expires after one successful connection.
    - `redirect_url` string, nullable — 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` string — Payroll only. Optional payroll embedded connection experience customization ID.
    - `items` string[] — 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.
    - `language` 'EN' | 'ES' | 'RU' | 'ZH' — Payroll only. Supported Link [display language](/link/initialization/overview#optional-initialization-parameters).
    - `mobile_app` boolean — Payroll only. Set to `true` when the session is used in a mobile app, including Hosted Link opened in a secure browser context.

## Response `200`

- ClientSession — Client connection session object.
  - `verification` string, uuid — Verification ID associated with the session.
  - `configuration` ClientSessionConfiguration — Connection session configuration for payroll and banking verifications.
    - `experience` string, uuid — Banking only. Optional bank connection experience customization ID.
    - `single_use_url` boolean — Banking only. If `true`, the session link expires after one successful connection.
    - `redirect_url` string, nullable — 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` string — Payroll only. Optional payroll embedded connection experience customization ID.
    - `items` string[] — 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.
    - `language` 'EN' | 'ES' | 'RU' | 'ZH' — Payroll only. Supported Link [display language](/link/initialization/overview#optional-initialization-parameters).
    - `mobile_app` boolean — Payroll only. Set to `true` when the session is used in a mobile app, including Hosted Link opened in a secure browser context.
  - `link` string — 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](/api-reference/verifications-guide#banking) 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` 'payroll' | 'banking' — Source of connection data.

---

[API](https://skmtc.dev/argyle/apis/users-api.md) · [All operations](https://skmtc.dev/argyle/apis/users-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argyle/users-api/revisions/73a1a5c56823/schema)