Create a new connect session

Create a new connect session for an employer

POST /connect/sessions

JavaScript

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  clientID: process.env['FINCH_CLIENT_ID'], // This is the default and can be omitted
  clientSecret: process.env['FINCH_CLIENT_SECRET'], // This is the default and can be omitted
});

const response = await client.connect.sessions.new({
  customer_id: 'x',
  customer_name: 'x',
  products: ['benefits'],
});

console.log(response.session_id);

201

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "connect_url": "https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000"
}

NOTE: The connect session uses Basic Auth; in the sample request above use client_id as the username and client_secret as a password. For example: Authorization: Basic <base64 encoded client_id:client_secret>

Authorizations

Authorization · string · header · required

Please use base64 encoded client_id:client_secret

Headers

Finch-API-Version · string<date> · default: 2020-09-17 · required

Header used to specify the version for a given API request. Current version is 2020-09-17.

Pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))

Body

application/json

customer_id · string · required

Unique identifier for the customer

Required string length: 1 - 255

customer_name · string · required

Name of the customer

Required string length: 1 - 255

products · enum<string>[] · 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.

Available options: benefits, company, deduction, directory, documents, employment, individual, payment, pay_statement, ssn

customer_email · string<email> | null

Email address of the customer

redirect_uri · string | null

The URI to redirect to after the Connect flow is completed

minutes_to_expire · number | null

The number of minutes until the session expires (defaults to 129,600, which is 90 days)

Required range: 1 <= x <= 129600

sandbox · enum<string> | null

Sandbox mode for testing

Available options: finch, provider, null

manual · boolean | null

Enable manual authentication mode

integration · object

Integration configuration for the connect session

Show child attributes

Response

201

application/json

Created

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