Finch Connect is the interface your customers will use to provide consent, approve permissions, connect their HR or payroll system, and authenticate. Finch will walk each employer through the appropriate flow based on the provider and auth method. Finch Connect is supported via our Frontend SDKs for Javascript and React. You can embed Finch Connect into your application, or set up a redirect flow.
This section requires that you have created a Finch application and have access to a client_id and client_secret by completing the Create a Finch Developer Account section.

​
Session Configuration

Every flow requires you to create a Finch Connect session with your client_id and client_secret and is configurable with the following parameters:
ParameterRequiredDescription
customer_idtrueA unique identifier for your customer.
customer_nametrueThe name of your customer.
customer_emailfalseThe email associated to your customer.
productstrueA space-separated list of permissions your application is requesting access to. See Product Permissions for a list of valid permissions. Please note that SSN is its own product scope.
redirect_uriredirect onlyThe URI your user is redirected to after successfully granting your application access to their system. This value must match one of your application’s configured redirect URIs.
integration.provideroptionalAn optional parameter that allows you to bypass the provider selection screen by providing a valid provider_id from our list of Providers.
integration.auth_methodoptionalAn optional parameter that allows you to bypass the provider selection screen by providing a valid auth_method for a provider from our list of Providers.
sandboxfalseAn optional value that allows users to switch on sandbox mode to connect to test environments. Allowed values: finch and provider. For more information, read our testing guide.
manualfalseAn optional value which when set to true displays both Automated and Assisted Providers on the selection screen.
minutes_to_expirefalseAn optional value which allows you to set the number of minutes the connect session should be valid for. Defaults to 30 days.
connection_idreauthentication onlyA unique identifier created when an employer successfully authenticates through Finch Connect. This ID is only used for reauthentication. You will not have a connection_id for the first call. For all reauthentication flows you should include the connection_id to avoid duplicate connections being created.

​
Create a Connect Session

Using the configuration params described in the above sections, your backend application will make a call to Create a New Connect Session POST /connect/sessions. When creating the connect session, include your internal customer_id for your customer, the customer’s name and any of the optional fields listed below.
React
import Finch from '@tryfinch/finch-api';

const client = new Finch({
  clientId: 'My Client ID',
  clientSecret: 'My Client Secret',
});

async function main() {
  const createConnectSessionResponse = await finch.connect.sessions.new({
	  products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
	  customer_id: customer.id, // Your internal customer ID
	  customer_name: customer.name, // Your customer's name
	  customer_email: customer.email, // The email associated to your customer (optional)
	  integration: { // (optional)
			  provider: 'adp_run', // The provider you wand to show up in connect (optional)
			  auth_method: 'credential' // The auth method of the provider to show up (optional)
	  },
	  minutes_to_expire: 43200, // How long you want the session to last for (defaults to 30 days)
	  redirect_uri: '' // The URI to redirect to for the redirect connect flow (optional)
	  sandbox: false // create a sandbox session for a sandbox app (optional)
	  manual: false // A value that, when set to true, displays both Automated and Assisted providers on the selection screen (optional)
  });

	/**
	 * {
	 *   "session_id": "<A unique session ID that can be used with embedded connect>",
   *   "connect_url": "<The url of the connect session for the redirect flow>"
   * }
	**/
  console.log(createConnectSessionResponse);
}

main();
If your customer has successfully authenticated (completed Finch Connect and you see a Live connection on your dashboard) and you call POST /connect/sessions using the same customer_id you passed in, Finch will prompt you to re-authenticate instead and return the following error: 
{
    "code": 400,
    "finch_code": "connection_already_exists",
    "message": "There's an existing connection for the customer_id: <session.customer_id>. Please use the /connect/sessions/reauthenticate endpoint instead.",
    "name": "bad_request",
    "context": {
      "customer_id": "<session.customer_id>",
      "connection_id": "<connection.id>"
    },
  }
If your customer has not yet successfully authenticated and you call POST / connect/sessions using the same customer_id you passed in, Finch will simply refresh the connect session and return the same session_id. You can do this if you wish to update the Customer Name or any other parameter before your customer connects. If you wish to update any parameters after the customer has connected, you will need to use POST / connect/sessions/reauthenticate.

​
Best Practices: Creating Sessions

​
DO

  • Always pass in a stable and unique customer_id for a given employer, and reuse the same customer_id across retries or drop-offs. Even if an employer opens the Connect session multiple times before successfully connecting, using the same customer_id ensures all attempts are tracked as a single staged session.
  • If you think an employer intends to connect multiple entities or payroll systems, you can append an identifier to the customer_id to differentiate the Connect sessions (e.g.: acme-1, acme-2). Visit this Help Center article for more details.

​
DON’T

  • Avoid generating new customer_ids on retries or failed connection attempts - this results in multiple redundant staged connections and could result in unintended behavior:
    • If an employer converts using Session_Link_1, Session_Link_2 will eventually expire
    • If an employer converts using both Session_Link_1 and Session_Link_2, they will inadvertently create two connections.

​
Reauthentication Sessions

Your application should be able to generate a Finch Connect session for reathentication. This will avoid creating duplicate connections and ensure that the user is able to reauthenticate successfully to continue syncing data. If a connection goes into a status of reauth, you will need to create a reauthentication session. This is done by calling Create a new Connect session for reauthentication (POST /connect/sessions/reauthenticate) endpoint with the connection_id of the connection that requires reauthentication. The response will include a new session_id and connect_url for the reauthentication session.

​
Launch Finch Connect - choose your preferred flow (redirect or embedded)

Finch provides two options to launch Finch Connect. For both options the user will go through the same authentication flow in Finch Connect.
  • The redirect flow is helpful in instances where you do not have a user interface and will share a link to Finch Connect with your customer, such as in an email or a link in your application.
  • The embedded flow is helpful when you want to host the authorization experience yourself, such as in a web application or mobile app. This allows you to keep your users within your application while they go through Finch Connect.
Using the response of the API call above, either launch Finch Connect by passing the session_id to the Finch Connect SDK or direct your customer to the URL provided in the response.

​
Redirect Flow

In this method of integrating Finch Connect, your application redirects your user’s browser to Finch Connect hosted by Finch on https://connect.tryfinch.com. After a successful connection, Finch Connect will redirect your user back to a URI you specified (redirect_uri) with a short-lived authorization code. The redirect_uri must be set in the Finch Developer Dashboard. Otherwise, the request will fail. Navigate to the URL in connect_url from the API response to initiate the redirect flow. The redirect authorization flow consists of four steps:
  1. Open Finch Connect — Your application redirects your user’s browser to Finch Connect to initiate the authorization flow.
  2. Obtain consent — Finch Connect prompts your user to log in to their employment system and grant your application access to the permissions you are requesting.
  3. Retrieve the authorization code — If your user successfully connects and grants your application access to their system, Finch Connect will redirect their browser to a specified redirect_uri with a short-lived authorization code.
  4. Exchange the code for an access token — Before sending API requests, your application will exchange the short-lived code for a long-lived access_token that your application will use to call the Finch API to retrieve data. Please read the Retrieve An Access Token section for more details on how to exchange the code for an access token.

​
Embedded Finch Connect

The Finch-provided SDKs embed the Finch Connect screen into your application. The user will remain entirely on your application throughout the process. When the onSuccess event is called by the SDK, simply pass the code to your internal callback endpoint as a query parameter.
NOTE: You should not include a redirect_uri if using the embedded flow. Because the entire flow is already self-contained in your app, no redirect is necessary.
  • React SDK: If you’re using React as your frontend framework, use the React SDK. Import the Finch Connect component and include it in your application. You can find examples and usage instructions in the SDK documentation or continue to follow this tutorial. - npm install --save @tryfinch/react-connect - yarn add @tryfinch/react-connect
  • JavaScript SDK: If you’re using a different frontend framework or vanilla JavaScript, use the pure JavaScript SDK. Include the Finch Connect library in your application, either by adding a script tag to your HTML file or by importing it as a module.
  • <script src="https://prod-cdn.tryfinch.com/v2.0.0/connect.js"></script>
    Since Finch Connect is an iFrame that requires interactivity, the HTML page that is loading Finch Connect must be served from a server. If the page is hosted statically, Finch Connect will not work properly.

​
React

React
import React, { useState } from "react";
import { useFinchConnect } from "@tryfinch/react-connect";

const App = () => {
const [code, setCode] = useState(null);

  // Define callbacks

  /**
   * @param {string} code - The authorization code to exchange for an access token
   * @param {string?} state - The state value that was provided when launching Connect
   */
  const onSuccess = ({ code, state }) => setCode(code);
  /**
   * @param {string} errorMessage - The error message
   * @param {'validation_error' | 'employer_error'} errorType - The type of error
   *    - 'validation_error': Finch Connect failed to open due to validation error
   *    - 'employer_connection_error': The errors employers see within the Finch Connect flow
   */
  const onError = ({ errorMessage, errorType }) => console.error(errorMessage, errorType);
  const onClose = () => console.log('User exited Finch Connect');

  // Initialize the FinchConnect hook
  const { open } = useFinchConnect({
    onSuccess,
    onError,
    onClose,
  });
};

​
JavaScript

Javascript
<html>
  <head>
    <script src="https://prod-cdn.tryfinch.com/v2.0.0/connect.js"></script>
  </head>
  <body>
    <button id="connect-button">Open Finch Connect</button>

    <script>
      // Define callbacks

      /**
       * @param {string} code - The authorization code to exchange for an access token
       * @param {string?} state - The state value that was provided when launching Connect
       */
      const onSuccess = ({ code, state }) => {
        // Exchange code for access token via your server
      };
      /**
       * @param {string} errorMessage - The error message
       * @param {'validation_error' | 'employer_error'} errorType - The type of error
       *    - 'validation_error': Finch Connect failed to open due to validation error
       *    - 'employer_connection_error': The errors employers see within the Finch Connect flow
       */
      const onError = ({ errorMessage }) => {
        console.error(errorMessage);
      };
      const onClose = () => {
        console.log('Connect closed');
      };

      const connect = FinchConnect.initialize({
        onSuccess,
        onError,
        onClose,
      });
    </script>
  </body>
</html>

​
Implement the authentication flow in your application

Add a button or a link in your application that triggers the Finch Connect flow. Users will click this button or link to start the authentication process.

​
React

React
const App = () => {
  // Generate a session ID using the /connect/sessions endpoint on the Finch API
  // See the docs here https://developer.tryfinch.com/api-reference/connect/new-session#create-a-new-connect-session
  const sessionId = '';

  return (
    <div>
      <header>
        <p>Code: {code}</p>
        <button type="button" onClick={() => open({ sessionId })}>
          Open Finch Connect
        </button>
      </header>
    </div>
  );
};

​
JavaScript

Javascript
<html>
  <head>
    <script src="https://prod-cdn.tryfinch.com/v2.0.0/connect.js"></script>
  </head>
  <body>
    <button id="connect-button">Open Finch Connect</button>

    <script>
      // Generate a session ID using the /connect/sessions endpoint on the Finch API
      // See the docs here https://developer.tryfinch.com/api-reference/connect/new-session#create-a-new-connect-session
      const sessionId = '';

      const button = document.getElementById('connect-button');
      button.addEventListener('click', () => {
        connect.open({ sessionId });
      });
    </script>
  </body>
</html>

​
Listen for events

Finch Connect emits events that your application should listen for to handle the different stages of the authentication process. The two most important events are onSuccess and onError.
  1. onSuccess: This event is triggered when the user completes the authentication process. It returns an authorization code that you will use to obtain an access_token in the next step. Pass this authorization code securely and temporarily to the access token exchange function. Please read Retrieve An Access Token section for more details on how to exchange the code for an access token.
  2. onError: This event is triggered if there’s an issue during the authentication process. Your application should handle this error gracefully, either by displaying an error message to the user or retrying the authentication flow.
  3. onClose: This event is triggered when a user exits the Finch Connect model, either by closing the modal or clicking outside the modal.

​
Checkpoint + Next Step

After completing this step, you will have successfully integrated Finch Connect into your application’s front end. This will enable users to authenticate with their employment systems, providing your application with the necessary authorization to Retrieve An Access Token in the next section.

​
Learn more