To get started using the Finch APIs, sign up for a free Finch Developer account to receive application credentials (a client_id and client_secret) and pilot how Finch works in our sandbox — a safe testing environment with mock data.

Sign Up

  1. Go to the Finch Developer Dashboard and sign up for a new account. You’ll need to provide your name, company name, email address, and create a password.
  2. Once you have created an account and logged in, locate the sandbox application in the upper left which was automatically created.
  3. Upon creating the application, you’ll be provided with a client_id and client_secret. You will use these credentials to authenticate your application to obtain access tokens in order to call the Finch APIs.
  4. Set up a secure method for storing your client_id, client_secret, and future access_tokens to prevent unauthorized access. Here are some methods to securely store these credentials:
    • Environment Variables: Store your client_id and client_secret as environment variables within your application. When your application needs to use these credentials, it can access them from the environment variables without exposing them in your source code.
    • Secure Database: Store the access tokens in a secure database with proper encryption and access controls in place. Make sure to use a database that supports encryption at rest and in transit to ensure the security of the stored tokens.
    • Secrets Management Solutions: Utilize a specialized secrets management solution, such as HashiCorp Vault or AWS Secrets Manager. These tools provide additional layers of security, access control, and auditing capabilities to ensure the safe storage of your client_id, client_secret, and access_token.
    • When storing access tokens, also store any relevant metadata, such as the associated employer ID. This will help you maintain data integrity and prevent mixing up tokens across different employers. This topic is covered in more detail in Store Tokens.
  5. Choose the products (commonly called “scopes”) that your application will need access to. Products determine the specific data your application can access and the actions it can perform. Each product refers directly to a Finch endpoint.
  6. (Optional) if you are using the Finch Connect Redirect Flow, specify any Redirect URIs for your application. This URL must be hosted on your own server or a trusted domain. Example: https://your-trusted-domain.com/api/finch/callback

The Finch Developer Dashboard is your centralized place to manage your Finch Applications, view current connections, review request activity, and set up webhook alerts.

Finch Developer Dashboard

Product Scopes

  1. Company - If your application requires access to company data, such as company legal name, office addresses, or Employer Identification Number (EIN) consider authorizing the company API.

  2. Directory - If your application needs to list all active and inactive employees at the company, consider authorizing the directory API.

  3. Individual - If your application requires personal information about individuals, such as their names, contact information, or dates of birth, consider authorizing the individual API.

  4. Employment - If your application needs information about individuals’ employment, such as job title or department, start and end dates, or employee income, consider authorizing the employment API.

  5. Payment - If your application needs information about a company’s payroll, such as payment dates or total amounts, consider authorizing the payment API.

  6. Pay-Statement - If your application requires detailed information about individuals’ pay statements, such as gross pay, earnings, employee deductions, or employer contributions consider authorizing the pay-statement API.

  7. Benefits - All the above endpoints are “read-only” endpoints. If your application requires the ability to write back employee deductions or employer contributions directly to the employer’s provider, consider authorizing the benefits API.

Redirect URIs

To authorize with Finch, you’ll need to provide one or more redirect URIs. The user will be redirected to the specified URI upon successfully authorizing your application access to their employment system. On redirect, the URI will contain an authorization code query parameter that must be exchanged with Finch’s authorization server for an access token.

Finch’s embedded Frontend SDKs don’t need to set up a redirect URI. The default redirect URI https://tryfinch.com is already applied.

The redirect URIs must match one of the following formats—

ProtocolFormatExamples
HTTPA localhost URI with protocol http://http://localhost:8000
HTTPSA URI with protocol https://https://example.com

Checkpoint + Next Step

After completing this step, you should have registered for a Finch Developer Dashboard account and set up a sandbox application, using your unique client_id and client_secret. You should also have a clear understanding of the Finch products that your application requires. You now have everything necessary to Set Up Finch Connect to begin connecting to employment providers.

Learn more