FinchSandbox

The Finch sandbox is a self-contained testing environment that simulates the live Finch production API. The sandbox provides a shielded space where you can test your API integration with Finch by creating mock payroll and HRIS providers and watching how requests respond differently based on the provider's data field compatibility, all without touching any live provider accounts.

By using sandbox providers, you can test and debug your apps without referencing any real employees or live employers. The sandbox lets you operate your application in a safe environment and provides a way to fine-tune your Finch processes before you move your product into production.

Supported features

The Finch sandbox mirrors the features on the Finch production servers. While some Finch features do not apply to the sandbox, such as Finch Connect Flow, data syncing schedule, webhooks, rate limiting, and the Benefits endpoints (in progress), the sandbox has the same Finch API feature set as the live environment. You can test your Finch processes in the sandbox since they will behave the same in the sandbox environment as they do on production servers.

The sandbox currently supports 29 mock providers. All sandboxes are deleted 24 hours after creation.

  • ADP Run - `adp_run`
  • Bamboo HR - `bamboo_hr`
  • Bamboo HR (API) - `bamboo_hr_api`
  • HiBob - `bob`
  • Gusto - `gusto`
  • Humaans - `humaans`
  • Insperity - `insperity`
  • Justworks - `justworks`
  • Namely - `namely`
  • Paychex Flex - `paychex_flex`
  • Paychex Flex (API) - `paychex_flex_api`
  • Paycom - `paycom`
  • Paycom (API) - `paycom_api`
  • Paylocity - `paylocity`
  • Paylocity (API) - `paylocity_api`
  • Personio - `personio`
  • Quickbooks - `quickbooks`
  • Rippling - `rippling`
  • Sage HR - `sage_hr`
  • Sapling - `sapling`
  • Squoia One - `sequoia_one`
  • Square Payroll - `square_payroll`
  • Trinet - `trinet`
  • Trinet (API) - `trinet_api`
  • Ulti Pro - `ulti_pro`
  • Wave - `wave`
  • Workday - `workday`
  • Zenefits - `zenefits`
  • Zenefits (API) - `zenefits_api`

The sandbox currently supports the following endpoints:

Organization

Payroll

Management

Sandbox

Quickstart Guide

Test your application by creating a sandbox for each provider you plan on integrating. While testing, use the sandbox providers in place of live providers.

First, create a sandbox provider by calling the https://sandbox.tryfinch.com/api/sandbox/create endpoint and specifying a provider_id and various products (employee_size is optional. Default is `10`. Max is `200`). The following curl command makes an HTTP POST request with a JSON encoded request body.

NOTE: Each sandbox is automatically deleted after 24 hours. You can either save the responses or create a new sandbox.
curl https://sandbox.tryfinch.com/api/sandbox/create \
  -X POST \
  -H "Content-Type: application/json" \
  --data-raw '{
    "provider_id": "gusto",
    "products": ["company", "directory", "individual", "employment", "payment", "pay_statement"],
    "employee_size": 10
  }'

The response to this request will contain a JSON encoded object containing a payroll_provider_id, company_id, an access_token, and a sandbox_time.

{
	"payroll_provider_id": "gusto",
	"company_id": "4620d0ad-5f45-45ec-aa1c-6adc92e4d46c",
	"access_token": "<your_access_token>",
	"sandbox_time": {
		"unix": 1693319558697,
		"calendar": "Tue Aug 29 2023 14:32:38 GMT+0000"
	}
}

Now that you have a valid access_token (for the sandbox), you will use this access token to send requests to the Finch Sandbox APIs from now on.

Use the following curl command to make a request to get the full employee directory from the /directory endpoint.

curl https://sandbox.tryfinch.com/api/employer/directory \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json'

The response to this request will contain a list of all employees in the payroll system (both active and inactive)

{
	"paging": {
		"count": 10,
		"offset": 0
	},
	"individuals": [
		{
			"id": "c7ba4905-27ed-462d-991e-68cca6cbc62b",
			"first_name": "Paula",
			"middle_name": "Scout",
			"last_name": "Borer",
			"manager": {
				"id": "e7cb438e-cdfc-469f-bd6d-717ee4f104b2"
			},
			"department": {
				"name": "Markets"
			},
			"is_active": false
		},

        .
        .
        .

		{
			"id": "29612e3a-9b89-4b2f-9223-9881eea98e05",
			"first_name": "Stacey",
			"middle_name": "Claudia",
			"last_name": "Bosco",
			"manager": {
				"id": "d1ea0d72-6854-4356-b447-0f7276023f77"
			},
			"department": {
				"name": "Intranet"
			},
			"is_active": false
		}
	]
}
Notice that there are only two active employees (is_active=true).

To simulate a real scenario of an new employee onboarding, we will call the POST https://sandbox.tryfinch.com/api/sandbox/employee endpoint.

curl --request POST \
  --url https://sandbox.tryfinch.com/api/sandbox/employee \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json'

The response will contain the specific fields person, individual, and employment corresponding to the individual’s information contained to the /directory, /individual, and /employment endpoints.

{
	"person": {
		"id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d",
		"first_name": "Bradford",
		"last_name": "Senger",
		"middle_name": "Theodore",
		"department": {
			"name": "Intranet"
		},
		"manager": {
			"id": null
		},
		"is_active": true
	},
	"individual": {
	  ...fields
	},
	"employment": {
      ...fields
	}
}

You can call the GET https://sandbox.tryfinch.com/api/employer/employment endpoint to learn more about that person as an employee.

curl --request POST \
  --url https://sandbox.tryfinch.com/api/employer/employment \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
	"requests": [
		{ "individual_id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d" }
	]
}'

{
	"responses": [
		{
			"individual_id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d",
			"code": 200,
			"body": {
				"id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d",
				"first_name": "Bradford",
				"middle_name": "Theodore",
				"last_name": "Senger",
				"title": "Customer Branding Associate",
				"manager": {
					"id": null
				},
				"employment": {
					"type": "employee",
					"subtype": null
				},
				"department": {
					"name": "Intranet"
				},
				"start_date": "2023-08-29",
				"end_date": null,
				"is_active": true,
				"class_code": "9710",
				"location": {
					"line1": "364 Cronin Bridge",
					"line2": "Suite 000",
					"city": "Harristown",
					"state": "NM",
					"postal_code": "55221-6282",
					"country": "US"
				},
				"income": {
					"unit": "yearly",
					"amount": 17195951,
					"currency": "USD",
					"effective_date": "2023-08-29"
				},
				"income_history": [],
				"custom_fields": []
			}
		}
	]
}

Let’s simulate the passing of time by advancing the sandbox clock at least 16 days (in order to simulate a biweekly payroll being processed).

curl --request POST \
  --url https://sandbox.tryfinch.com/api/sandbox/clock \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "daysToAdvance": 16
  }'

{
	"unix": 1694701958697,
	"calendar": "Thu Sep 14 2023 14:32:38 GMT+0000"
}

Now that the employee has worked at the company for at least one payroll cycle, let’s call the GET https://sandbox.tryfinch.com/api/employer/payment endpoint to validate the employee is one of the individuals on the pay run.

Since the sandbox clock was initially set to August 29, 2023 upon creation, and we advanced the clock 16 days to September 14, 2023, we will pass a start_date of 2023-08-16 and an end_date of 2023-08-31 to get the last pay run in the month of August.

curl --request GET \
  --url 'https://sandbox.tryfinch.com/api/employer/payment?start_date=2023-08-16&end_date=2023-08-31' \
  --header 'Authorization: Bearer <your_access_token>'

Notice that the employee’s individual_id is listed in the pay run’s individual_ids array. Also keep in mind that all amounts are in USD cents (not dollars).

[
	{
		"id": "f094a207-5d01-4229-b411-20fcea09a338",
		"pay_period": {
			"start_date": "2023-08-16",
			"end_date": "2023-08-31"
		},
		"pay_date": "2023-09-01",
		"debit_date": "2023-09-01",
		"company_debit": {
			"amount": 1750795,
			"currency": "usd"
		},
		"gross_pay": {
			"amount": 1562372,
			"currency": "usd"
		},
		"net_pay": {
			"amount": 604433,
			"currency": "usd"
		},
		"employee_taxes": {
			"amount": 858414,
			"currency": "usd"
		},
		"employer_taxes": {
			"amount": 119521,
			"currency": "usd"
		},
		"individual_ids": [
			"c441bc94-99f8-4ed9-ae54-d37f34f8e9d8",
			"7a4d7aa3-c522-4fad-8a68-d6fe67d7f54c",
			"635bf8ef-5e77-4312-a2a5-e68eb2d9942d"
		]
	}
]

To simulate an employee termination event, call the DELETE https://sandbox.tryfinch.com/api/sandbox/employee endpoint. Remember, in sandbox time, the calendar date is 16 days ahead.

curl --request DELETE \
  --url https://sandbox.tryfinch.com/api/sandbox/employee/635bf8ef-5e77-4312-a2a5-e68eb2d9942d \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json'

"Individual 635bf8ef-5e77-4312-a2a5-e68eb2d9942d terminated"

The last step is to validate the employee is set to inactive by calling the POST https://sandbox.tryfinch.com/api/employer/employment endpoint and passing their individual_id in the request body.


curl --request POST \
  --url https://sandbox.tryfinch.com/api/employer/employment \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requests": [
      { "individual_id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d" }
    ]
  }'

Their end_date should be 16 days after their start_date.

{
	"responses": [
		{
			"individual_id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d",
			"code": 200,
			"body": {
				"id": "635bf8ef-5e77-4312-a2a5-e68eb2d9942d",
				"first_name": "Bradford",
				"middle_name": "Theodore",
				"last_name": "Senger",
				"title": "Customer Branding Associate",
				"manager": {
					"id": null
				},
				"employment": {
					"type": "employee",
					"subtype": null
				},
				"department": {
					"name": "Intranet"
				},
				"start_date": "2023-08-29",
				"end_date": "2023-09-14",
				"is_active": false,
				"class_code": "9710",
				"location": {
					"line1": "364 Cronin Bridge",
					"line2": "Suite 000",
					"city": "Harristown",
					"state": "NM",
					"postal_code": "55221-6282",
					"country": "US"
				},
				"income": {
					"unit": "yearly",
					"amount": 17195951,
					"currency": "USD",
					"effective_date": "2023-08-29"
				},
				"income_history": [],
				"custom_fields": []
			}
		}
	]
}

Learn more

Learn more about Finch, take a look at the following resources: