This guide details how developers at Check Ecosystem Partners can securely access customer data that lives in Check to power a product experience through one or more of Check's existing Partners.

There are four important entities that will be referred to throughout this document:

Check — this is us! 👋
Partner — this is a customer of Check. The Partner is the entity who ultimately owns the payroll customer relationship with the employer, and is aiming to deliver an integrated experience to that customer through a software platform built on top of Check and enhanced by the Ecosystem Partner.
Ecosystem Partner — this is you! You would like to read and/or write customer payroll data that lives within Check on behalf of a Check Partner.
Employer — this is the end employer running payroll on the Partner’s software. They grant access to the Ecosystem Partner to their payroll data in order to power an additional experience within the Partner’s software.

Process Overview

Check's Partners build payroll products on top of Check's infrastructure.
Employers sign up to run payroll on the product of one of Check’s Partners. In the course of this customer relationship they may sign up for additional services, some of which may be offered by an Ecosystem Partner.
If and when an Employer grants consent for an Ecosystem Partner to access their data to unlock an additional service, the Partner makes an API call to Check to authorize the Ecosystem Partner to access that Employer’s data.
At this point, Check sends an authorization code to the Ecosystem Partner, which can then be exchanged for an access token. That token is effectively equivalent to an API key, but has scoped access pursuant to the Ecosystem Partner and permission level, and the specific employer in question.
Finally, an Employer may or may not have a direct relationship and/or login to the Ecosystem Partner’s product or website.
Optionally, the Ecosystem Partner can also be signed up to receive webhooks from Check, so it is notified when payroll data changes for the Employers it has been granted access to, without polling.

Technical Details

Creating an OAuth Access Token

All requests made by an Ecosystem Partner to retrieve payroll data, and create, update, or delete API objects should use an OAuth Access Token.

In order to receive an OAuth access token, a Check Partner must first make a request to grant the Ecosystem Partner access to a specific company’s data.

This request will look like the below. You can find more information on this API request here.

curl \
  -H "Authorization: Bearer <Partner API Key>" \
  "https://sandbox.checkhq.com/integrations/partners/{integration_id}/authorize"
  -d '{
    "integration_permission": "{integration_permission_id}",
    "company": "{company_id}",
    "tos_timestamp": "{timestamp_of_tos_signature}",
    "product_purchase_timestamp": "{timestamp_of_product_purchase}"
  }'

When this request is made, Check will send a callback request to a redirect URI specified by the Ecosystem Partner. The request that Check makes will contain an authorization code, which can be exchanged for an access token.

Expectations for your Redirect URI

Your redirect URI should expect a receive the following data as query parameters:

code: The code will be exchanged for an access token in the next step, which will enable you to make authenticated calls against Check's API
company: The company parameter contains the public ID of the Check company for which you are being granted an authorization code.
partner: The partner parameter contains the public ID of the Check partner that owns the company in question.

GET "https://integration.partner.com/auth/check/callback?code={code}&company={company}&partner={partner}"

Query Parameters:
	code={code}	
	company={company}
	partner={partner}

Expected Response: None

Status: 200

How to Exchange the Code for a Token

Once you receive the code from the call above, you should make a POST request with the code included in the form data to retrieve a set of access and refresh tokens.

POST "https://sandbox.checkhq.com/oauth/token/"

Headers:
 "Content-Type: application/x-www-form-urlencoded"

Request (form data):
  "client_id={client_id}"
  "client_secret={client_secret}"
  "code={authorization_code}"
  "redirect_uri=https://integration.partner.com/auth/check/callback"
  "grant_type=authorization_code"

Response:
{
  "access_token": "{access_token}",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "...",
  "refresh_token": "{refresh_token}"
}

How to Refresh an Access Token Using a Refresh Token

POST "https://sandbox.checkhq.com/oauth/token/"

Headers:
 "Content-Type: application/x-www-form-urlencoded"

Request (form data):
  "client_id={client_id}"
  "client_secret={client_secret}"
  "refresh_token={refresh_token}"
  "grant_type=refresh_token"

Response:
{
  "access_token": "{new_access_token}",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "...",
  "refresh_token": "{new_refresh_token}"
}

Receiving Webhooks as an Ecosystem Partner

In addition to reading data through the API, Ecosystem Partners can be signed up to receive webhooks from Check. This lets you react to changes in payroll data as they happen — for example, a new employee being added, a payroll being paid, or a benefit being updated — rather than polling Check's API on a schedule.

How to sign up

Ecosystem Partner webhook configs are provisioned by Check rather than through the POST /webhook_configs endpoint, which is reserved for Check Partners. To get set up, send the following to your Check representative:

The URL where Check should deliver webhooks, for each environment you want to receive them in (sandbox and/or production).
The topics you are interested in, if you'd like guidance on which events to expect. See Webhook event types for the full list.

Check will create a webhook config owned by your Ecosystem Partner account and share the config's signing key with you. Use this key to verify the Check-Signature header on every request, as described in The shape of your webhook endpoint.

Which webhooks you receive

Ecosystem Partner webhooks are scoped by the same permissions that govern your API access:

Only for authorized companies. You receive webhooks only for Employers who have granted you access through the authorization flow described above. Once an integration access is revoked, webhooks for that company stop.
Only for resources you can retrieve. A webhook for a resource is delivered only if your integration permission includes retrieve access for that resource (e.g. employee:retrieve for employee webhooks, payroll:retrieve for payroll webhooks). Events for resources outside your scope are not sent.
Integration access events. Most Ecosystem Partner permissions include integration_access:retrieve, which means you also receive an integration_access webhook when an Employer authorizes you, when the access is updated, and when it is revoked. This is the recommended way to learn about new authorizations in addition to the redirect URI callback above.

Request format

Ecosystem Partner webhooks use the same request format, headers, retry behavior, and signature scheme as standard Check webhooks. One additional header is included:

Check-IntegrationAccess-ID: the public ID (iac_...) of the integration access under which the webhook was sent. Use this to map the request back to the specific Employer authorization, particularly if you receive webhooks for many companies across multiple Check Partners.

POST https://integration.partner.com/check/webhooks

Headers:
  Check-Live: true
  Check-Topic: employee
  Check-WebhookEvent-ID: whe_7uCODm8JFmZyov9jL8QO
  Check-Signature: <hex-encoded HMAC-SHA-256 of the body using your webhook key>
  Check-IntegrationAccess-ID: iac_fVSfFvta4PucEMEe4Tsg

Body:
{
  "event": "updated",
  "data": { ... }
}

Your endpoint should respond with a 2xx status code within 5 seconds; otherwise Check will retry delivery on an exponential backoff schedule. See The shape of your webhook endpoint for guidance on building a reliable, idempotent handler.