Getting started

The FranchiseSEE REST API lets your own systems read performance data and manage locations, districts, location groups and users. Every request is authenticated with a bearer token, and every response is JSON.

Base URL#

All endpoints live under one host:

https://app.franchisesee.com/api

Resource endpoints are versioned under /api/v1 (for example /api/v1/locations). Two endpoints sit outside the version prefix: GET /api/user and POST /api/custom-metrics.

Create an API token#

1. Sign in to FranchiseSEE.
2. Open the profile menu in the top right, choose User settings, then choose API tokens.
3. Name the token, choose its permissions and how long it lasts, and create it.
4. Copy the token straight away. It is shown only once.

Each token belongs to your account and acts as you. Keep it as secret as a password.

Who sees API tokens depends on your account:

• HQ (franchisor) accounts with the Manage API tokens permission can create tokens with any permission, including tokens that never expire.
• Franchisee accounts can create tokens only when their brand has AI connections on and has turned on Let franchisees create personal tokens. A franchisee token is always read-only and always expires (after 30 days, 90 days or a year).

Token permissions#

When you create a token you choose which of four permissions it carries:

GET /api/user is the one exception: any authenticated token may call it, whatever its permissions. Use it to confirm which account a token acts as.

A token can never do more than your account can. Its effective access is the overlap of your own account permissions and the permissions you gave the token:

• A full administrator can still create a read-only token to hand to a reporting integration. That token can only read, even though the account can write.
• Giving a token create does nothing if the account that owns it can't create that kind of resource.

The token screen shows a live "What this token will be able to do" preview before you create a token, and you can change a token's permissions later.

Make your first request#

Send the token in the Authorization header with the Bearer scheme, and ask for JSON:

curl https://app.franchisesee.com/api/user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

A successful call returns the account the token acts as:

{
  "data": {
    "id": "6e2b9d41-8c7a-4f3e-b1d5-9a0c2e4f6b81",
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "perspective": "franchisor",
    "location_id": null,
    "has_sso_auth": true,
    "roles": ["franchisor_admin"],
    "created_at": "2025-03-14T15:22:08.000000Z",
    "updated_at": "2026-10-02T09:41:55.000000Z"
  }
}

Then list your locations:

curl "https://app.franchisesee.com/api/v1/locations?page[size]=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Collections are paginated, and most can be filtered, sorted and expanded with related records. See Querying collections.

What a token can see#

A token sees exactly what its owner sees when they sign in:

• HQ accounts see every location in the brand.
• Franchisee accounts see only the locations assigned to them. Asking for any other location returns 403 Forbidden.

Data never crosses brands: every token is scoped to its owner's organization.

Rate limits#

The /api/v1 endpoints allow 60 requests per minute per user. Every token you own shares that allowance, so give busy integrations their own user account if they need their own limit. Going over returns 429 Too Many Requests with a Retry-After header. See Errors.

Keep tokens safe#

• Never share a token or commit it to version control.
• Keep tokens in environment variables or a secrets manager, not in code.
• Give each integration its own token with only the permissions it needs, so you can revoke one without breaking the others.
• Rotate tokens regularly, and delete any you no longer use.
• Always call the API over HTTPS.