Skip to main content

​
What is the difference between automated and assisted integrations?

Integration type describes how Finch sets up and runs the data sync between the provider and Finch. It does not change how your application reads the data — both types are delivered through the same Finch API and the same standardized data model.
  1. Automated — Finch syncs data from the provider automatically once the connection is created, on a 24-hour cadence.
  2. Assisted — Finch manages the sync with the provider and refreshes data on a 7-day cadence.
Both cadences describe how often Finch reads fresh data from the provider. They do not govern writes: deduction changes are submitted to the provider near-real-time on automated connections, and within a 2 business day SLA on assisted ones. See Write Deductions for write timing and payroll cutoffs. Employers authenticate through Finch Connect for both. Automated integrations use OAuth, credentials, or an API token; assisted integrations use third-party admin credentials. Assisted integrations also require a one-time configuration period before data is available. See Integration Types for full cadences and configuration periods.

​
Why are some Finch API endpoints GET requests while others are POST requests?

In the Finch API, some endpoints are GET requests (/company and /directory endpoints) while some are POST requests (/individual and /employment endpoints). The latter are POSTs because a request body containing ids needs to be sent. Additionally, the /individual, /employment, and /pay-statement endpoints are special because they are “batch” endpoints, meaning you can send as many ids as you want in the body, and get a single response back containing the information for as many individuals/pay-statements as you sent. Query parameters can’t handle 1000 ids in the URL, hence the need for POSTs using request bodies.

​
Does Finch display payments to business/vendor subcontractors?

No. Finch only includes payments to people who appear in the employee directory with an associated individual_id. This applies across all providers.

​
How is the data returned by Finch validated for accuracy?

Finch looks at two broad categories when defining data quality:
  1. Rate of NULL fields when values exist in the system.
  2. Rate of incorrect fields. The rate at which Finch returns NULL can indicate one of four things:
  • The data is unavailable in the system — not a Finch error
  • The data is available in the system, but the format does not cleanly fit our endpoint — error
  • We parsed the wrong field and the data we parsed does not fit the expected format — error
  • We parsed information, but we did not know how to classify it — error
The goal is to decrease the rate of NULL over time; if the data is available in the provider’s system, Finch should be returning that data. The status of an employee (full-time vs. contractor) also affects which fields return NULL. Finch defines the “rate of incorrect data” as data that does not match what is reported in the provider’s system. This could either mean the field returns blank indicating a potential bug in our code (e.g.: a pay statement array returns empty), or the field returns a value that does not reflect what is reported in the system. We have an internal dashboard where we track data field coverage and correctness in real-time. We have alerts defined to notify us of any anomalies detected which we proactively investigate and fix. There are several ways developers can validate data coming from Finch:
  1. Implementing “quality checks” on all pay statements to make sure financial data is not missing, duplicated, or inaccurate.
  2. Running a series of “blind” audits on a semi-regular schedule. The audits should focus on the two categories mentioned above: rate of nulls and the rate of incorrect data. Employee employment status, currency amounts, and field type categorizations are important data points to watch.
There are two ways to conduct an audit of Finch data:
  1. The data returned from Finch is compared with previous Finch-connected employer data that have similar providers, use cases, and sizes. Any discrepancies are alerted to Finch. This method is beneficial if you have thorough historical data to pull from.
  2. If you do not have enough historical data to use, the data returned from Finch can be compared directly with the data in the provider’s system. This method requires contacting the employer and asking either pointed questions about possible data discrepancies or exchanging data extensively.
Giving your own customers a way to report suspected discrepancies is also useful. Forward anything they report to Finch for investigation. Finch runs automated tests, checks, and audits internally to catch data quality errors, and fixes reported errors as they are confirmed. If specific audits or data fields matter to your business, tell your Developer Success Representative so Finch can account for them.

​
Can I bypass the provider selection screen in Finch Connect?

Yes. If you already know the employer’s provider, pass a valid provider_id in the integration.provider field when you create the initial Connect session. Finch Connect then sends the employer straight to that provider instead of the selection screen. See the Providers endpoint for a full list of valid provider IDs, and Bypass the provider selection screen for implementation guidance. Reauthentication sessions skip the selection screen on their own. The connection_id you pass already identifies the employer’s provider, so the employer goes straight to reauthenticating it — you don’t need to set integration.provider.

​
How long is the access token lifetime?

A Finch access_token does not expire unless you disconnect it. If a connection returns a 401 with a finch_code of reauthenticate_user — because the employer changed a security setting, or the provider made an infrastructure change — Finch cannot read data for that connection until the employer reauthenticates through Finch Connect. Completing the reauthentication session creates a new access_token, which Finch returns to your application.

​
How does Finch encrypt data? What type of encryption is used?

Finch uses several encryption protocols to protect data at rest and in transit.
  • Encryption at rest — All data in our datastores are encrypted using AES-256 with keys managed via AWS KMS.
  • Encryption in transit — All data to or from the Finch infrastructure is encrypted in transit using TLS 1.2.
  • Application-level encryption — Other Highly Restricted fields are additionally encrypted at the application level using AES-256.