Ecosystem Partner Guide
Learn how to integrate with Check's API as an Ecosystem Partner.
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
IDs and Credentials
The authorization flow uses several IDs that are easy to mix up. Check provides all of them except the redirect URI, which you register with Check.
| Value | Format | Where it comes from | How it is used |
|---|---|---|---|
| Integration partner ID | int_... | Check assigns it to you. | Identifies you as an Ecosystem Partner. The Check Partner puts it in the path of the authorize request. |
client_id and client_secret | Random strings | Check issues them to you, one pair per environment. | You send them to /oauth/token/ to exchange codes and refresh tokens. |
| Redirect URI | HTTPS URL | You register it with Check, one per environment. | Check sends the authorization code to this URL. You send the same value as redirect_uri when you exchange the code. |
| Partner ID | pro_... | Check sends it in the partner query parameter of the callback. | Identifies the Check Partner that owns the company, not you. You do not send it to Check. |
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 -X PUT \
-H "Authorization: Bearer <Partner API Key>" \
-H "Content-Type: application/json" \
"https://sandbox.checkhq.com/integrations/partners/{integration_partner_id}/authorize" \
-d '{
"integration_permission": "{integration_permission_id}",
"company": "{company_id}",
"tos_timestamp": "{timestamp_of_tos_signature}",
"product_purchase_timestamp": "{timestamp_of_product_purchase}"
}'
{integration_partner_id} is your integration partner ID (int_...). The request body does not include a redirect URI.
When this request is made, Check sends a callback request to your registered redirect URI. The request contains an authorization code, which you exchange for an access token.
Expectations for your Redirect URI
Your redirect URI is the endpoint on your server where Check delivers authorization codes. Send it to your Check representative for each environment (sandbox and production) when your integration is set up. Check stores one redirect URI per environment. The authorize request does not accept a redirect URI, so you cannot choose a different one per request. If you need different behavior for different employers, route the request on your server after it arrives.
Check calls your redirect URI with a GET request from Check's servers and includes a Check-IntegrationAccess-ID header with the public ID (iac_...) of the integration access. Your endpoint should receive the following query parameters:
code: The authorization code. Exchange it for an access token in the next step.company: The public ID (com_...) of the Check company that granted you access.partner: The public ID (pro_...) of the Check Partner that owns the company. This is not your integration partner ID.
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}"
}
The redirect_uri you send must exactly match the redirect URI registered with Check for that environment. Check compares the two strings character for character, so a different scheme, host, path, or trailing slash causes a mismatch. Use the sandbox redirect URI and credentials with https://sandbox.checkhq.com and the production ones with https://api.checkhq.com. If the values do not match, Check responds with status 400:
{
"error": "invalid_request",
"error_description": "Mismatching redirect URI."
}Each authorization code can be exchanged once and expires 24 hours after Check issues it. If the Check Partner authorizes the same company again, codes from the earlier authorization stop working after 30 seconds. Exchanging a used, expired, or replaced code returns status 400 with "error": "invalid_grant".
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
retrieveaccess for that resource (e.g.employee:retrievefor employee webhooks,payroll:retrievefor 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 anintegration_accesswebhook 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.
Updated 8 days ago

