Skip to main content
The Finch Sandbox is a testing environment with mock connections that mirror the field and functionality of Finch’s production integrations. You can configure connections to test scenarios your application needs to handle. New to Finch? Start with How the Finch API is organized. The four-diagram tour covers every core entity and how they connect in about five minutes.
Sandbox connections require your sandbox client_id and client_secret. Find these in the Finch Dashboard under your sandbox application’s settings. Production credentials will not work for sandbox connections.

​
Creating a sandbox connection

finch and provider are the only accepted values for the sandbox parameter. See Provider Sandboxes for provider mode.
The Sandbox API sets the connection’s authentication method from the authentication_type you pass — it does not go through Finch Connect, which in production only offers the method a provider supports. A provider can support different products across its authentication methods: one method may support Deductions while another does not. When the method you choose does not support a product on your session, /employer requests for that product return a 501 not_implemented_error.Confirm your authentication_type supports the products you are testing before you create the connection. Check the provider’s authentication_methods — and each method’s benefits_support for Deductions — through the /providers endpoint or the Field Support matrix.

​
Sandbox credentials

Finch Connect presents the authentication method supported by the provider and handles the flow — your application has no logic to implement for authentication. Use the credentials below that match the authentication method shown in Finch Connect for your test.
In production, Finch Connect presents only the authentication method supported by the connected provider. Most providers support a single method. The sandbox exposes all flows so you can understand how each one behaves.

​
Credential flows

​
API token flows

​
OAuth flows

All OAuth auth methods bypass the provider OAuth flow in sandbox mode. Clicking Connect immediately succeeds. OAuth providers do not support multi-entity testing — use providers with credential-based authentication to test multi-entity flows.

​
Testing multi-entity employers

Use the multi_entity password to simulate a payroll system where a single login manages multiple entities. Finch Connect displays an account selection screen with each entity as a separate option.
Providers that use OAuth flows cannot be used for multi-entity testing. The multi_entity password only applies to credential-based authentication.
To create multiple connections with the same provider where each connection has entities available, use distinct company usernames — see Testing distinct companies. An entity can only be authenticated on one connection at a time. Using the same base username across connections maps to the same underlying company — entities already connected under that company will not be available on new connections.
Additional technical detail on multi-entity testing behavior is available in the Finch Help Center, accessible to current customers on any Finch plan.

​
Testing distinct companies

To test multiple distinct companies with the same provider, append a number to the base username when creating each connection: Each numbered username generates a unique company with its own ID and data set. This mirrors production behavior — the username an employer uses to authenticate determines which company Finch connects to. Two connections authenticated with the same username will always map to the same company for that provider.

​
Configuring sandbox data

Each sandbox connection is pre-populated with 20 randomly generated employees, corresponding employment and individual records, and one company payment dated to the current date with one pay statement per full-time employee. Use the /sandbox endpoints to modify connection data:
After modifying data, run a refresh data sync to see changes reflected in /employer API responses. Data syncs do not run automatically in the Finch Sandbox.

​
Testing job failures

Use the sandbox to test how your application handles asynchronous job failures before encountering them in production. This applies to data syncs and write-back operations such as deductions enrollments. Use Configure Sandbox Job to set the expected completion_status for a job type, then trigger it with Enqueue a New Sandbox Job. Verify your application handles the failure response correctly. Job configurations persist until you explicitly change them.

​
Testing webhooks

The Finch Sandbox fires webhook events for sandbox connections the same way it does in production. See Webhooks for the full list of events and payload shapes. To receive webhook events, set up a webhook endpoint in the Finch Dashboard under the Webhooks tab for the Sandbox application/environment.
If the Webhooks tab is not visible, confirm you have an Editor or Admin role in the dashboard — any Admin member can update your role. If you have the correct role and still don’t see the tab, contact developers@tryfinch.com with your client_id to request that webhooks be enabled.

​
Testing assisted integrations

Organization and Payroll endpoints behave the same way in sandbox regardless of integration type. Some Deductions endpoints are only available for automated integrations. When an sandbox connection is created for an automated integrations, the connection is active immediately. Assisted integration connections start in a pending state in sandbox, reflecting the manual processing they require in production. To simulate a full assisted integration:
  1. Create a connection using any of the three methods, following the assisted setup for each method in the table above.
  2. The connection status starts as pending. For connections that are assisted for deductions and automated for organization and payroll, the organization and payroll statuses will be connected. If you do not complete the following steps within 3 days, the pending status will change to Error No Account Setup, which matches behavior in production. /employer requests made while the connection is pending return a 202 response, matching production behavior for assisted integrations.
  3. Call Update a sandbox account to set the status to connected.
  4. Call any /employer endpoint to retrieve data for the connection.
  5. Use the /sandbox endpoints to configure connection data. Run a refresh data sync after each change.
The manual parameter defaults to false, which excludes assisted integrations from the Finch Connect provider list. Set manual=true and sandbox=finch in your session to include them.

​
Testing deductions

Some integrations are automated for Organization and Payroll but assisted for Deductions. To test this scenario, create a connection using the assisted setup above, then follow the assisted path in step 1 below.
Deductions endpoints work only when the connection’s authentication method supports Deductions. If Get All Deductions returns a 501, verify the method through the /providers endpoint — see Creating a sandbox connection.
  1. Get a benefit_id:
    • Automated — Call Get All Deductions or Create Deduction. Get All Deductions returns the benefit_id directly with no job to track.
    • Assisted — Call Create Deduction or Register Deduction. This returns a job_id — call Retrieve a Manual Job and confirm the status is complete before continuing.
  2. Call Enroll Individuals in Deduction with the benefit_id. This returns a job_id.
  3. Call Retrieve a Manual Job with the job_id to verify enrollment status and result codes.
In the Finch Sandbox, benefits created through the deductions endpoints do not appear on pay statements. To add specific benefits to pay statements, use the sandbox payment endpoints when configuring sandbox data.

​
Connection limits

The Finch Sandbox supports up to 100 connections. Disconnected and staged connections do not count toward the limit. There is no disconnect option in the Finch Dashboard UI. Use the Disconnect endpoint to disconnect a connection. Store your access tokens so you can disconnect connections when testing is complete.

​
Rate limits

  • API rate limits are doubled compared to production.
  • Sandbox connections allow 10 refresh data syncs per hour (production allows 1).

​
Checkpoint + Next Step

After completing this step, you can simulate the employment scenarios your application will encounter with live employers. Once your integration is ready, move on to testing with provider demo accounts.

​
Learn more