Finch Sandbox

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.

To use the Finch Sandbox, simply visit the “Connections” tab of your sandbox application in the Finch Dashboard, or open Finch Connect with the sandbox query parameter set to finch.

​

Simulating Connect

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 connections via API

You may create and configure Finch Sandbox connections directly via API without going through Finch Connect. This can be particularly helpful for repeatable testing, for example during automated testing scenarios.

​

Creating new accounts

• POST /sandbox/connections will create a completely new connection with a single account.
• POST /sandbox/connections/accounts will create a new account for an existing connection. This is useful for understanding what it looks like if a user authenticates twice through Finch Connect with two different accounts.

​

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

​

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.

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:

• PUT /sandbox/company to modify company data
• POST /sandbox/directory to add new individuals to a company
• PUT /sandbox/employment/{individual_id} to modify employment information for a specific individual
• PUT /sandbox/individual/{individual_id} to modify individual information for a specific individual
• POST /sandbox/payment to add a new payment for a company

​

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, 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. It is helpful to keep the following in mind while testing assisted connections in the Finch Sandbox:

• 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. You can then use the /sandbox/connections endpoint to update the connection 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 updated after the user completes the assisted flow.
• 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.

​

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

​

Learn more

• Quickstart
• Set Up Finch Connect