Finch Sandbox

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.

​

Creating a sandbox connection

​

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.

​

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. 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.

​

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:

• PUT /sandbox/company — modify company data
• POST /sandbox/directory — add individuals
• PUT /sandbox/employment/{individual_id} — modify employment data
• PUT /sandbox/individual/{individual_id} — modify individual data
• POST /sandbox/payment — add a payment
• PUT /sandbox/connections/accounts — modify connection status

​

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.

​

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.
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.

​

Testing deductions

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.

​

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

​

Learn more

• Quickstart
• Set Up Finch Connect
• Finch Sandbox — Advanced Testing