Create a new connect session

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/v2"
	"github.com/Finch-API/finch-api-go/v2/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>"
  },
  "recordkeeping": {
    "plan_id": "<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>'
    ],
    'recordkeeping' => [
        'plan_id' => '<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"
  }
}

{
  "code": 401,
  "finch_code": "invalid_client",
  "message": "Invalid client: Unable to validate credentials"
}

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/v2"
	"github.com/Finch-API/finch-api-go/v2/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>"
  },
  "recordkeeping": {
    "plan_id": "<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>'
    ],
    'recordkeeping' => [
        'plan_id' => '<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"
  }
}

{
  "code": 401,
  "finch_code": "invalid_client",
  "message": "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.

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,

plans,

plans_dependents,

plans_enrollments,

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. Required if you use the redirect flow, and it must be registered on the Credentials tab of the Finch Developer Dashboard. Omit it for the embedded flow (Connect SDK).

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

Show child attributes

recordkeeping

object | null

Optional recordkeeping configuration. Can only be provided when the recordkeeping product is requested. Currently supports recordkeeper set to voya, empower, fidelity, or transamerica.

Show child attributes

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

Organization

Payroll

Deductions

Benefits

Documents

Connect

Management

Sandbox

Development Guides

Create a new connect session

Authorizations

Headers

Body

Response