---
title: "Create a new connect session"
method: POST
path: "/connect/sessions"
tags: ["Connect"]
---

# Create a new connect session

`POST /connect/sessions`

Create a new connect session for an employer

## Headers

- `Finch-API-Version` string, date, required

## Request body

- CreateConnectSessionRequest
  - `customer_id` string, required — Unique identifier for the customer
  - `customer_name` string, required — Name of the customer
  - `customer_email` string, email, nullable — Email address of the customer
  - `products` ConnectProducts[], required — The Finch products to request access to. Use `benefits` to access deductions endpoints — `deduction` is a deprecated alias that is still accepted but should not be combined with `benefits`.
  - `redirect_uri` string, nullable — The URI to redirect to after the Connect flow is completed
  - `minutes_to_expire` number, nullable — The number of minutes until the session expires (defaults to 129,600, which is 90 days)
  - `sandbox` 'finch' | 'provider' | 'null', nullable — Sandbox mode for testing
  - `manual` boolean, nullable — Enable manual authentication mode
  - `integration` object, nullable — Integration configuration for the connect session
    - `provider` string, required — The provider to integrate with
    - `auth_method` 'assisted' | 'credential' | 'oauth' | 'api_token' | 'null', nullable — The authentication method to use

## Response `201`

Created

- CreateConnectSessionResponse
  - `session_id` string, required — The unique identifier for the created connect session
  - `connect_url` string, uri, required — The Connect URL to redirect the user to for authentication

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

## Changes

> 53 revisions in range; 3 could not be searched.

- **2026-06-10** `25f30f2c7227` — 1 info
  - added the new `recordkeeping` enum value to the request property `products/items/`
- **2025-11-04** `b817e7a30a63` — 1 breaking, 7 info
  - the request property `integration/provider` became not nullable
  - the request property `customer_email` became optional
  - the request property `integration` became optional
  - the request property `integration/auth_method` became optional
  - …4 more
- **2025-10-27** `0105d239fcaf` — 8 breaking, 2 info
  - the request property `customer_email` became required
  - the request property `integration` became required
  - the request property `integration/auth_method` became required
  - the request property `integration/provider` became required
  - …6 more
- **2025-06-24** `f7e741bc6e01` — 2 info
  - the endpoint scheme security `basicAuth` was added to the API
  - the `minutes_to_expire` request property's max was increased from `43200.00` to `129600.00`
- **2025-04-22** `a9dc15ba77c4` — 2 info
  - added the new `deduction` enum value to the request property `products/items/`
  - added the new `documents` enum value to the request property `products/items/`

[Full history](https://skmtc.dev/finch-api/apis/api-reference/changes/connect/sessions/post.md)

---

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