API docs by Redocly

Check Cherry App Credentials (Legacy) (v1)

Download OpenAPI specification:

This page covers the original way an app authenticated to a customer's account: a single App ID and App Secret pair, sent with every request along with the ID of the customer you are acting for.

Most apps should use OAuth instead. New apps are set up on OAuth from the start; the flow is in the App Platform guide. If your app already runs on App ID and App Secret, it keeps working, and the last section below covers moving over.

Authentication

Your App ID and App Secret are on your app's page in the developer portal. Send them as headers on every request, together with the customer's Check Cherry account ID as FRANCHISE-ID:

curl -H "App-ID: <app id>"      -H "App-Secret: <app secret>"      -H "FRANCHISE-ID: <customer's account id>"      https://api.checkcherry.com/api/v1/leads

All three are also accepted as query parameters (app_id, app_secret, franchise_id). Prefer headers; query strings end up in logs.

Which accounts you can act for. Only accounts that have enabled your app from their Integrations page. A FRANCHISE-ID for any other account resolves to nothing and the request fails as unauthorized.

Finding a customer's account ID. You receive it when they enable your app: it is the {{franchise_id}} substitution available to your app's authentication endpoint and widget HTML, and every webhook payload carries it as franchise_id.

What the credential can do. A fixed set of permissions, the same for every app and every account. It covers leads, proposals and bookings, appointments, expenses, availability, messaging, users, media, offerings, reports, and design templates. It is deliberately broad, which is one of the reasons to prefer OAuth: an OAuth app declares exactly what it needs and nothing more.

Requests and responses are the same as for any other credential. See the Business API reference for every endpoint, the JSON:API response format, pagination, and rate limits.

Moving to OAuth

Your app can support both credentials at once, so there is no cut-over day.

  1. Open your app's OAuth page in the developer portal, enable OAuth, and declare the permissions your app actually uses. Set an Install URL.
  2. Implement the authorization flow from the App Platform guide. Store the tokens you receive per customer.
  3. For each request, use the customer's OAuth token if you hold one; otherwise fall back to App ID and App Secret.
  4. Ask existing customers to connect through your Install URL. Each one who does gets their own token and appears on their Integrations page as an installed app.

Nothing in Check Cherry needs to change on the customer's side beyond that one authorization. Their existing enablement of your app stays in place, so requests that still use App ID and App Secret continue to work while you migrate.