Check Cherry App Platform (v1)

Base URL — All API requests should be made to:

https://api.checkcherry.com/api/v1/

Setup:

1. Join the Partner Program. Email support@checkcherry.com and we will set up your developer account.
2. Create your app at checkcherry.com/developer/apps. The name, logo, and links you enter are what customers see when they connect.
3. Open your app's OAuth page and turn it on. Fill in three things:
   • Redirect URL. The page on your site we send customers back to after they approve. Must be https://.
   • Permissions. What your app needs to do in the customer's account. Ask only for what you use; customers see this list before they approve.
   • Install URL. The page on your site where a customer clicks to connect. Check Cherry links customers there from their Integrations page.
4. Copy your Client ID. It identifies your app in the steps below. There is no secret to keep.

Once your app is published, every customer sees it on their Integrations page with a Connect button that opens your Install URL.

When a customer connects your app, you receive an access token for their account. Send it with every request:

curl -H "Authorization: Bearer <access_token>" https://api.checkcherry.com/api/v1/leads

The token already knows which business it belongs to, so there is nothing else to send. It can do exactly what your app's permissions allow; a request outside them returns 403.

Always send the token in the Authorization header, never in the URL.

When a token no longer works (it expired, or the customer disconnected your app), the API returns 401. Refresh it (see below). If refreshing fails too, ask the customer to connect again.

Built on App ID and App Secret? That method still works for existing apps and is documented in App credentials (legacy), along with how to move to OAuth.

Connecting works the same way as "Sign in with Google": the customer is sent to Check Cherry, approves your app, and is sent back to you with a code that you trade for a token. Check Cherry follows the OAuth 2.1 standard, so a standard OAuth library for your language will handle most of this. Point it at:

Authorization URL:  https://www.checkcherry.com/oauth/authorize
Token URL:          https://www.checkcherry.com/oauth/token

Your library will ask whether to use PKCE. Say yes, with the S256 method. If it asks for a client secret, leave it blank; your app doesn't have one.

Want to see it working first? Our sample apps include a complete connect flow you can run locally and copy from.

If you are doing it by hand, here is the whole flow.

1. The customer starts on your site. Before sending them to Check Cherry, make two random strings and save them in the customer's session:

• a verifier, which you will send back at step 3, and
• a state value, which you will check when the customer returns.

Hash the verifier with SHA-256, base64url-encode the result, and call that the challenge. Then send the customer to:

https://www.checkcherry.com/oauth/authorize
  ?response_type=code
  &client_id=<your client id>
  &redirect_uri=<your redirect URL>
  &code_challenge=<the challenge>
  &code_challenge_method=S256
  &state=<the state value>

2. The customer approves. They sign in to Check Cherry, see your app's name and logo, and see the full list of permissions you declared. They approve the whole list or cancel. Your app now appears on the customer's Integrations page.

3. Trade the code for a token. We send the customer back to your redirect URL with two query parameters: code and state. Check that state matches what you saved. Then, from your server, make this request:

POST https://www.checkcherry.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<the code>
&redirect_uri=<your redirect URL>
&client_id=<your client id>
&code_verifier=<the verifier you saved>

You get back:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "lead_read lead_create"
}

Save both tokens for this customer. The access token is what you send with API requests. It lasts one hour.

4. Get a new token when it expires. Use the refresh token:

POST https://www.checkcherry.com/oauth/token

grant_type=refresh_token
&refresh_token=<the refresh token>
&client_id=<your client id>

You get back a new access token and a new refresh token. Save both; the old refresh token stops working.

5. Disconnecting. A customer can disconnect your app from their Integrations page at any time. Your next request returns 401; stop calling the API for that customer. If they want to come back, they connect again from step 1. To disconnect from your side, send POST https://www.checkcherry.com/oauth/revoke with token and client_id.

Once you have a token, requests work exactly as described in the Business API reference. The short version:

• Send JSON, with the Content-Type: application/json header.
• Responses are JSON:API: a data object or array with attributes and relationships.
• Lists are paged. Pass page and per, and stop when page reaches meta.total_pages.
• Every endpoint lists the permission it needs. A request your app isn't permitted to make returns 403, and fields it isn't permitted to read (pricing, for example) come back as null.

Rate limiting — Typical usage will not hit a limit. If you do, Check Cherry returns 429 Too Many Requests with a Retry-After header. Wait that long and try again.

New endpoints, new fields, and newly documented behavior are listed at checkcherry.com/api/changelog.