Finch Connect is our embeddable User Interface (UI) that enables employers to connect their employment system to your application. Employers use Finch Connect to approve permissions, select their provider, and authorize access.

New to Finch Connect or looking for help getting started? Read the Finch Overview.

If you’ve implemented Finch Connect, but are seeing drop-off from employers or low connection completion rates, try the following suggestions below to optimize conversion. Before implementing these best practices, make sure you have a mechanism to track conversion rates so you can measure any improvements.

The suggestions below are listed in priority order.

1. Set Finch Connect as the default integration option

Rather than presenting Finch Connect and other manual flows as equal alternatives, encourage your customers to use Finch as the default. You can always include an option to ‘skip this step’, and offer the manual flows as a back up. You can also play with the size, positioning, and color of your entry point to Finch Connect, or test out labels like “Recommended” or “Preferred” to encourage usage.

Finch Connect Best Practices 1.jpg

2. Include extra messaging for context

Setting the right expectations is crucial for successful onboarding through Finch Connect. Your app should explain the value of connecting their employment system to your app, what to expect during setup, and how their data will be handled securely.

Finch Connect Best Practices 4.jpg

Explain the value of connecting

The value for employers will depend on your use case, but may include:

  • Eliminate security risks associated with sharing PII manually
  • Remove manual work required to onboard new employee cohorts to the system
  • Decrease data discrepancies between systems of record
  • Streamline the onboarding experience for employees
  • Ensure terminated employees are removed from the system in a timely manner

The following are a few examples of how you might introduce Finch Connect in your onboarding flow.

Tell the user what to expect

Before launching the Finch Connect module, explain to the user that they will be prompted to connect their payroll or HRIS system with Finch. Explain what data your app will collect, and why. If the user doesn’t have their credentials on hand, you can give them the option to ‘skip and come back later’ — but make sure to encourage them to connect later.

Emphasize data security

Let users know that Finch is secure, and all data is encrypted in transit and at rest. Explain that your app does not have access to their credentials, and that they can choose to disconnect at any time. Feel free to share a link to Finch’s Trust Center for more information.

3. Create multiple opportunities to connect

If a user does not connect their employment system during the onboarding process, you can remind them to come back later. Try in-app messaging or email automations to remind them to connect, and why. You can also use these channels to notify users if re-authentication is needed.

4. Deploy Finch early in the onboarding process

While employer authorization process is quick, a full syncing of the provider’s data can take some time. That’s why we recommend embedding Finch Connect as early as possible in the onboarding process. While data cannot be retrieved until the synchronization is complete, you can take advantage of this time to continue your core onboarding process, collecting additional information or showing your product tutorial.

Finch Connect Best Practices 2.jpg

You can programmatically add visual cues to show when the data import is complete. Finch provides a List All Automated Jobs endpoint to monitor the status. Once the job’sstatus moves to complete, you can now call Finch’s various endpoints to read the data. A new job is created to sync the employer’s data 24 hours from the previous sync.

{
  "paging": {
    "count": 1,
    "offset": 0
  },
  "meta": {
    "quotas": {
      "data_sync_all": {
        "allowed_refreshes": 1,
        "remaining_refreshes": 1
      }
    }
  },
  "data": [
    {
      "job_id": "a3d1410c-864b-45ce-8d7f-a063914015a0",
      "job_url": "https://api.tryfinch.com/jobs/automated/a3d1410c-864b-45ce-8d7f-a063914015a0",
      "status": "pending",
      "created_at": "2023-08-23T18:05:13.146Z",
      "scheduled_at": "2023-08-24T18:05:23.282Z",
      "started_at": "2023-08-24T18:05:27.329Z",
      "completed_at": null,
      "type": "data_sync_all"
    },
  ]
}
{
  "paging": {
    "count": 1,
    "offset": 0
  },
  "meta": {
    "quotas": {
      "data_sync_all": {
        "allowed_refreshes": 1,
        "remaining_refreshes": 1
      }
    }
  },
  "data": [
    {
      "job_id": "c6d96ca1-01b0-49dd-81af-d354fa7e9cf2",
      "job_url": "https://api.tryfinch.com/jobs/automated/c6d96ca1-01b0-49dd-81af-d354fa7e9cf2",
      "status": "pending",
      "created_at": "2023-08-24T18:07:05.329Z",
      "scheduled_at": "2023-08-25T18:02:23.282Z",
      "started_at": null,
      "completed_at": null,
      "type": "data_sync_all"
    },
    {
      "job_id": "a3d1410c-864b-45ce-8d7f-a063914015a0",
      "job_url": "https://api.tryfinch.com/jobs/automated/a3d1410c-864b-45ce-8d7f-a063914015a0",
      "status": "complete",
      "created_at": "2023-08-24T18:05:13.146Z",
      "scheduled_at": "2023-08-24T18:05:23.282Z",
      "started_at": "2023-08-24T18:05:27.329Z",
      "completed_at": 2023-08-24T18:07:05.329Z,
      "type": "data_sync_all"
    },
  ]
}

5. Remove unnecessary points of friction

Each additional step in the employer onboarding journey is an opportunity for drop off. While the following suggestions will not work for every use case, we encourage developers to consider the following to remove any unnecessary points of friction in Finch Connect.

  1. Customize provider order
  2. Bypass the provider selection screen
  3. Set up preferred Authentication Method(s)
  4. Set up authentication fallback
  5. Notify users that they need to reauthenticate

Customize provider order

If you want providers to be shown in a different order than Finch’s default alphabetical order, you can pin providers to the top of Finch Connect, and re-order them as you see fit. This can help you key in on providers that are most relevant to your customer base and reduce the friction of connecting. Pinning and re-ordering can be done through the Finch Dashboard.

You can also use this feature to hide providers that are not relevant to your customer base. This will reduce the number of options your customers have to choose from, and reduce the likelihood of them selecting the wrong provider.

Bypass the provider selection screen

If you already know which provider(s) your customers use (or want to use), you can skip or limit the provider selection screen in Finch Connect.

This removes three possible friction points:

  1. If you already know which provider is being used by the customer, you can skip an extra step in the Finch Connect flow.
  2. If you want to avoid the customer choosing the wrong provider (e.g. many different versions of ADP), then you can suggest the right version.
  3. If you want to better own the user experience, you can build your own provider selection page and launch Finch Connect with the right provider each time.

The provider selection screen can be skipped by providing a valid provider_id in the payroll_provider option while opening Finch Connect.

If you don’t know the customer’s payroll system upfront or you want to give the customer as many options to connect as possible, then leave the payroll_provider option empty while opening Finch Connect.

Bypass Enabled
https://connect.tryfinch.com/authorize?
&client_id=<your_client_id>
&products=company directory individual employment payment pay_statement
&payroll_provider=gusto
&redirect_uri=https://example.com
Bypass Disabled
https://connect.tryfinch.com/authorize?
&client_id=<your_client_id>
&products=company directory individual employment payment pay_statement
&redirect_uri=https://example.com

Custom integration page

If you want complete control over the user experience, you can also build your own provider selector screen and launch Finch Connect with the right provider each time.

Finch Connect Best Practices 3.jpg

In any case, bypassing the provider selector screen removes friction by eliminating the guesswork for customers during the set up process.

Set up preferred Authentication Method(s)

Finch often offers several authentication methods for employers, including OAuth, API Token, credentials, or adding a 3rd-party administrator. Authentication method(s) are dependent on provider.

As a developer, you have the flexibility to decide which authentication methods to make available for your end customers and their order of priority. You can set primary and secondary authentication methods for each provider, and even hide specific methods if desired. All of this is possible through the Finch Dashboard.

For example, if you want to present only the API token method to Bob customers, Finch can conceal the credentials-based authentication method in Finch Connect.

You can also disable an auth method across all integrations using our gloabl setting page. These settings will apply automatically to any new integrations that Finch introduces.

Set up authentication fallback

Authentication fallback enables employers to authorize through Finch Connect even when Finch is experiencing intermittent issues with a provider.

Fallback

If an employer encounters an error while attempting to authenticate via Finch Connect’s automated flow, Finch Connect will display manual connection instructions after three failed attempts*. This process involves the employer adding Finch as a third-party admin in their system. Once Finch accepts the invitation and sets up the account, the data for the connection will flow through the Finch API, just like any other automated connection. The primary distinction is that your application will receive a 202 response when making requests with that token until the connection is established on Finch’s end. Ensure that your application is configured to handle 202 response codes from Finch.

This feature applies only to credentials-based authentication methods, and not to other authentication methods like direct API token entry or OAuth.

Authentication fallback is currently supported for the following providers:

  • ADP Workforce Now
  • Paycom
  • Sequoia One

To request access to Authentication Fallback, please reach out to your Finch Account representative.

*The number of errors before displaying the fallback screen is adjustable. While the default value is set to three for every provider, this may change over time.

Notify users that need to reauthenticate

Finch aims to ensure your application maintains long-lived access to your users’ employment systems. However, when a user changes security settings on their account or an employment system makes changes to its infrastructure, Finch’s connection can get disconnected. This will result in an error with the HTTP status code of 401 and finch_code of reauthenticate_user. When an access token returns this, your user will need to reauthenticate by going through the Automated Connect Flow again.

To increase conversion, we recommend either using in-app or email notifications to notify your user there is an issue with their connection, why re-connecting is beneficial, and the steps they need to follow to re-connect. To create a more seamless experience, you can bypass the employment system selection page by using the payroll_provider parameter. You can find the payroll_provider of your user by calling the /introspect endpoint with their access_token.

Below are a couple of options to present the re-connection flow to your users—

  1. Prompt your user to log on to their application dashboard where you can present them the UI to go through Finch Connect again.
  2. Send your user an authorization URL with a redirect_uri that redirects them back to their application dashboard after a successful reconnection. Learn more about redirecting your users to Finch Connect.

Remember this will create a new access_token for your user that will be to be updated. Make sure to save this new token in your database.


Checkpoint + Next Step

After completing this step, your application will have many opportunities to optimize Finch Connection increase the completion rate. Even subtle changes can increase employer adotpion of your application dramatically. Determine which recommendations apply to your application the most and start there. Then continue to optimize your application by batching IDs in your requests to reduce endpoint calls.

Learn more