Skip to main content
POST
/
connect
/
sessions
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);
import os
from finch import Finch

client = Finch(
client_id=os.environ.get("FINCH_CLIENT_ID"), # This is the default and can be omitted
client_secret=os.environ.get("FINCH_CLIENT_SECRET"), # This is the default and can be omitted
)
response = client.connect.sessions.new(
customer_id="x",
customer_name="x",
products=["benefits"],
)
print(response.session_id)
package main

import (
"context"
"fmt"

"github.com/Finch-API/finch-api-go"
"github.com/Finch-API/finch-api-go/option"
)

func main() {
client := finchgo.NewClient(
option.WithClientID("4ab15e51-11ad-49f4-acae-f343b7794375"),
option.WithClientSecret("My Client Secret"),
)
response, err := client.Connect.Sessions.New(context.TODO(), finchgo.ConnectSessionNewParams{
CustomerID: finchgo.F("x"),
CustomerName: finchgo.F("x"),
Products: finchgo.F([]finchgo.ConnectSessionNewParamsProduct{finchgo.ConnectSessionNewParamsProductBenefits}),
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.SessionID)
}
package com.tryfinch.api.example;

import com.tryfinch.api.client.FinchClient;
import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
import com.tryfinch.api.models.ConnectSessionNewParams;
import com.tryfinch.api.models.SessionNewResponse;

public final class Main {
private Main() {}

public static void main(String[] args) {
FinchClient client = FinchOkHttpClient.fromEnv();

ConnectSessionNewParams params = ConnectSessionNewParams.builder()
.customerId("x")
.customerName("x")
.addProduct(ConnectSessionNewParams.ConnectProducts.BENEFITS)
.build();
SessionNewResponse response = client.connect().sessions().new_(params);
}
}
package com.tryfinch.api.example

import com.tryfinch.api.client.FinchClient
import com.tryfinch.api.client.okhttp.FinchOkHttpClient
import com.tryfinch.api.models.ConnectSessionNewParams
import com.tryfinch.api.models.SessionNewResponse

fun main() {
val client: FinchClient = FinchOkHttpClient.fromEnv()

val params: ConnectSessionNewParams = ConnectSessionNewParams.builder()
.customerId("x")
.customerName("x")
.addProduct(ConnectSessionNewParams.ConnectProducts.BENEFITS)
.build()
val response: SessionNewResponse = client.connect().sessions().new(params)
}
require "finch_api"

finch = FinchAPI::Client.new(client_id: "4ab15e51-11ad-49f4-acae-f343b7794375", client_secret: "My Client Secret")

response = finch.connect.sessions.new(customer_id: "x", customer_name: "x", products: [:benefits])

puts(response)
curl --request POST \
--url https://api.tryfinch.com/connect/sessions \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--header 'Finch-API-Version: <finch-api-version>' \
--data '
{
"customer_id": "<string>",
"customer_name": "<string>",
"products": [],
"customer_email": "jsmith@example.com",
"redirect_uri": "<string>",
"minutes_to_expire": 64800.5,
"manual": true,
"integration": {
"provider": "<string>"
}
}
'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tryfinch.com/connect/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customer_id' => '<string>',
'customer_name' => '<string>',
'products' => [

],
'customer_email' => 'jsmith@example.com',
'redirect_uri' => '<string>',
'minutes_to_expire' => 64800.5,
'manual' => true,
'integration' => [
'provider' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json",
"Finch-API-Version: <finch-api-version>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "connect_url": "https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000"
}
{
"code": 400,
"finch_code": "connection_already_exists",
"message": "There's an existing connection for the customer_id: {customer_id}. Please use the /connect/sessions/reauthenticate endpoint instead.",
"name": "bad_request",
"context": {
"customer_id": 1234567890,
"connection_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
{
"error": "Invalid client: Unable to validate credentials"
}
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,
recordkeeping,
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 | null

Integration configuration for the connect session

Response

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