Integrate Finch Connect Into Your Application
Before being able to pull data from an employment provider through Finch, your customer needs to consent to the data being transferred. Without consent, Finch is not authorized to pull the data on behalf of the customer. Finch Connect is our user-facing product to help you obtain customer consent, and it is a prerequisite step before calling Finch APIs.
session_id
. Configure Finch Connect
Every flow requires you to configure Finch Connect with the client_id
and is configurable with the following parameters:
Parameter | Required | Description |
---|---|---|
client_id | true | Your client_id , a unique identifier for your application. You can find this value in your Finch Developer Dashboard. |
products | true | A 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_uri | redirect only | The 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. |
state | optional | An optional value included as a query parameter in the response back to your application. This value is often used to identify a user and/or prevent cross-site request forgery. |
payroll_provider | optional | An optional parameter that allows you to bypass the provider selection screen by providing a valid provider_id from our list of Providers. |
sandbox | false | An 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. |
manual | false | An optional value which when set to true displays both Automated and Assisted Providers on the selection screen. |
category | false | The category of integrations your applications would like to expose. Currently only hris is supported. If no category is provided, defaults to hris . |
connection_id | true | connection_id is only used for reauthtication. 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 |
Choose your preferred authentication flow
Finch provides two options to setup Finch Connect. The redirect flow is helpful in instances where you do not have a user interface (such as a link in an email) or you prefer to redirect in order to not host the authorization experience yourself. For the embedded flow, Finch provides several Frontend SDKs for easy implementation.
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
.
Set the redirect_uri
parameter to the URL where users will be redirected after completing the authentication flow. The redirect_uri
must be set in the Finch Developer Dashboard. Otherwise, the request will fail.
https://connect.tryfinch.com/authorize?
&client_id=fdc8f543-bfb2-4463-883b-fa234106ca9d
&products=company directory individual employment
&redirect_uri=https://example.com
The redirect authorization flow consists of four steps:
- Open Finch Connect — Your application redirects your user’s browser to Finch Connect to initiate the authorization flow.
- 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.
- 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 authorizationcode
. - 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 represents your application’s access to your user’s employment system.
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/v1/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.
import React, { useState } from "react";
import { useFinchConnect } from "@tryfinch/react-connect";
const App = () => {
const [code, setCode] = useState(null);
const onSuccess = ({ code }) => setCode(code);
const onError = ({ errorMessage }) => console.error(errorMessage);
const onClose = () => console.log("User exited Finch Connect");
// 1. Initialize Finch Connect
const { open } = useFinchConnect({
clientId: "<your-client-id>",
products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
payrollProvider: "gusto", // optional
sandbox: "provider", // optional
state: "", // optional
onSuccess,
onError,
onClose,
});
// ...
};
<html>
<body>
<script>
const onSuccess = ({code}) => {
// exchange code for access token via your server
}
const onError = ({ errorMessage }) => {
console.error(errorMessage);
}
const onClose = () => {
console.log('Connect closed');
}
const connect = FinchConnect.initialize({
clientId: '<your-client-id>',
products: ['company', 'directory', "individual", "employment", "payment", "pay_statement"],
payrollProvider: "gusto", // optional
sandbox: "provider", // optional
state: "", // optional
onSuccess,
onError,
onClose,
});
</script>
</body>
</html>
Implement the authentication flow
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.
const App = () => {
// ...
// 2. Display Finch Connect
return (
<button type="button" onClick={() => open()}>
Open Finch Connect
</button>
);
};
<html>
<body>
<button id="connect-button">Open Finch Connect</button>
<script>
const button = document.getElementById('connect-button');
const connect = FinchConnect.initialize({
...
});
button.addEventListener('click', () => {
connect.open();
})
</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
.
onSuccess
: This event is triggered when the user completes the authentication process. It returns an authorizationcode
that you will use to obtain anaccess_token
in the next step. Pass this authorizationcode
securely and temporarily to the access token exchange function.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.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 frontend. 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
Was this page helpful?