The Finch Sandbox contains mock data that mirrors the field and functionality support of Finch’s production integrations, and allows you to configure connections into whatever scenario you need to test against.
Finch Sandbox connections can only be created using the sandbox client_id and client_secret found in your Finch Dashboard. You cannot use production credentials to create sandbox connections.Use sandbox=finch as a query parameter for the Finch Sandbox. sandbox=true is deprecated.

​
Initiating A Finch Sandbox Connection

You can initiate a connection in the Finch Sandbox three ways:
  1. Open the “Connections” tab of your sandbox application in the Finch Dashboard and click on the Actions > Create a New Connect Link button. Fill in the required Customer Name and Customer ID fields; all other fields are optional. Click Connect to generate your session URL. Copy the generated URL and paste it into a new browswer tab. See below for mock credentials to enter in Finch Connect. Note: this method returns an authorization code in the redirect, but it immediately creates a connection in the UI; it does not test the exchange of the authorization code for an access token.
  2. Use the regular Finch API endpoint, Create a New Session to launch Finch Connect. For authentication for the API call, use the client_id and client_secret found in your Finch Dashboard and pass in the sandbox=finch query parameter. See below for mock credentials to enter in Finch Connect. This method can be used to test the exchange of the authorization code for an access token.
  3. Use the sandbox endpoint Create a New Sandbox Connection. Use your sandbox client_id and client_secret from your Finch Dashboard to authenticate the API call. This is useful for repeatable testing, for example during automated testing scenarios. However, this method does not open the Finch Connect flow so does not test exchanged the authorization code for an access token.

​
Simulating Finch Connect Authentication

In Finch Sandbox mode, Connect simulates various scenarios to meet your testing needs. The credentials you use while logging in determine the behavior of the Finch Connect flow.

​
Simulating credential flows

For all credential flows, use the username good_user. The password will determine the steps presented in the flow:
  • For a simple credential flow with only the credential input page, use good_pass.
  • To show the MFA page, use the password mfa.
  • To show the account selection screen, use the password account_selection.
  • To show both MFA and account selection, use the password mfa_account_selection.

​
Simulating API token flows

  • Use good_token to trigger a successful auth. Any other value will result in an error.
  • Use good_user and good_pass for client_id and client_secret flows. Any other values will result in an error.

​
Simulating OAuth flows

All OAuth auth methods will bypass the provider OAuth flow when in sandbox mode. Clicking “Connect” will immediately result in success

​
Configuring data for a connection

Finch will pre-populate data for each sandbox connection you create with randomly generated data based on the scopes available on the connection. We will populate 20 employees with corresponding employment and individual data by default, along with one company payment whose pay date is the current date. The payment will contain one pay statement for each full-time employee.

​
Modifying existing accounts

  • PUT /sandbox/connections/accounts will modify the connection status of an existing account. For example you may want to change the connection_status of an existing automated account from connected to error_reauth to simulate a 401 error code response
If you would like to go beyond the pre-generated data, you can use the /sandbox endpoints to programmatically modify the data for your connections:
Sandbox connections function just like production connections in that a sync is required in order for data updates to be reflected by Finch’s /employer API endpoints. However, the data syncs do not run automatically every 24 hours in the Sandbox. Once you have configured new data via the endpoints above, be sure to run a refresh data sync to see the new data come through.

​
Asynchronous jobs

Finch’s API uses asynchronous jobs in several scenarios, such as data syncs and operations which write data back into a payroll system, such as deductions enrollments. In these scenarios, Finch returns a job_id to monitor the job’s progress. The Finch Sandbox allows you to modify the completion_status of jobs, for jobs with type data_sync_all configuring the end result a particular type of job should have. For example, you can configure a data sync job to have an error state to view a simulated error response: 
    curl https://api.tryfinch.com/sandbox/jobs/configuration \
      -X PUT \
      -H "Content-Type: application/json" \
      --data-raw '{
        "type": "data_sync_all",
        "completion_status": "error",
    }'
Then, when you run a job with POST /sandbox/jobs, the job will result in an error. Keep in mind that job completion configurations are persistent; once you set a completion state, each job you run will end in that state until you call PUT /sandbox/jobs/configuration to change the configuration again.

​
Assisted connections

The Finch Sandbox supports simulating assisted connections by simply choosing an assisted provider when creating a new connection. Follow the steps below to test assisted connections in the Finch Sandbox:
  • Either configure a connection via the sandbox API or set up Finch Connect in your testing environment and set manual=true and sandbox=finch. The Finch Connect flow embedded in your Sandbox application’s “Connections” tab in the Finch Dashboard will show only automated integrations.
  • After you obtain an access token for a simulated assisted connection, the connection will start out in a pending state.
  • Call the Update a sandbox account to update the status to connected to simulate the completion of the assisted connection. This accurately reflects the behavior of a live assisted connection, where the connection status is manually updated by our team after the accountant account is set up..
  • After the status is changed to connected, you will see data for the connection when calling any of the /employer endpoints.
  • As with automated connections, you can use the /sandbox endpoints to configure the data for the connection. Once you have configured new data, be sure to run a refresh data sync to see the new data come through.

​
Testing Deductions in the Finch Sandbox

  • Use the Get All Deductions, Create Deduction, or Register Deduction endpoints to get a benefit_id. Create and Register will also return a job_id. The job does not have to complete to use the benefit_id to call the Enroll Individuals in Deduction endpoint.
  • Use the benefit_id to call the Enroll Individuals in Deduction endpoint. This will return a job_id.
  • Call the Retrieve a Manual Job for any deductions job_id (both automated and assisted integrations) to see the job status. This will return a pending status at first. Once the status is completed you will see codes and messages regarding if the requests were successful.
  • For connections using assisted integrations, call the Enqueue a New Sandbox Job endpoint before calling the Retrieve a Manual Job endpoint to see the job status.

​
Sandbox Rate Limits

  • To make testing easier, API Rate limits are doubled in the Finch Sandbox.
  • Sandbox connections allow for 10 refresh data syncs per hour, as opposed to 1 per hour for production connections.

​
Checkpoint + Next Step

After completing this step, you have the ability to simulate many types of employment scenarios that your application may encounter when connecting to live employers. Continuously testing, validating, and reviewing your integration will help you stay ahead of potential issues and ensure that your application is making the most of Finch’s services. Once your application is ready, you can begin to connect live providers.

​
Learn more