Handling API Responses

​

Finch IDs

Finch IDs (UUIDs) remain constant for all company connections that utilize the same authentication method. However, if you have multiple access tokens for a company connection, and they were generated via different authentication methods, the Finch IDs may not be consistent across these tokens. For instance, if an employer first authenticates with credentials (username/password), and then later authenticates again using an API token auth method, the two access tokens generated from these authentications may have different Finch IDs. This is because the underyling employment system IDs used to identify an employee or payment may be different depending on the authentication method, and Finch maps its UUIDs to those underlying employment system IDs. You should keep this in mind when incorporating Finch integrations into your application.

​

Null Values

API responses can return null values for some fields. This can happen for a few different reasons—

1. The employment system does not support the field.
2. The field is supported by the employment system but the data has not been filled in by the payroll administrator of a company.
3. Finch was not able to infer a reasonable value (for example, the categorization of a tax).

​

202 Response Codes

In some cases, requests to the Finch API may return a 202 accepted. This is the response Finch returns when the connection is created, but data is not yet available. After data is available, this response will no longer be sent. This is often the case for async operations.

Requests that may return a 202 response include:

• Assisted Connect, including Assisted Deductions
• Pay statements which exist but have not yet been fetched
• Authentication fallback.
• Additional use cases may be added in the future.

All applications should be built to account for these 202 responses. The key behaviors your application should exhibit are:

• Retry: Your application should retry the request after a delay. For assisted connections, keep in mind that the SLA for first data sync is 14 days.
• Backoff: If the request continues to return a 202 response, your application should increase the delay between retries.
• Do not try to process the data until a successful response is received.

Examples of 202 Responses:

{
  "code": 202,
  "name": "accepted",
  "finch_code": "data_sync_in_progress",
  "message": "The pay statements for this payment are being fetched. Please check back later."
}

{
   "code": 202,
   "name": "authorization_pending",
   "finch_code": "pending",
   "message": "Authorization to this company's data is pending"
}