Leal developer portal

Quickstart

Three steps from a fresh account to a stamped loyalty card.

1. 1. Create an API token

   Sign in to Leal, open API tokens in your account settings, and create a token. Treat it like a password: it carries the full access of the user who created it.

   Open API tokens

2. 2. List your stores

   Every request needs an Authorization header. Start by listing the stores your token can reach, and note the account id you want to work with.

   curl https://app.getleal.com/api/v1/accounts \
     -H "Authorization: Bearer $LEAL_API_TOKEN"

3. 3. Add a stamp to a customer card

   Stamping is the call most integrations need. Pass the account, the customer and the customer card, and Leal updates the wallet pass and sends the notification.

   curl -X POST \
     https://app.getleal.com/api/v1/accounts/1/customers/2/customer_cards/3/stamp \
     -H "Authorization: Bearer $LEAL_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"stamps": 1}'

Authentication

Leal uses bearer API tokens. Create one in your account settings at app.getleal.com/api_tokens, then send it on every request:

Authorization: Bearer YOUR_TOKEN

A token inherits the access of the user who created it, so it can reach every store that user belongs to. There is no separate sandbox environment yet, so test against a store you do not mind changing.

Errors

Every failure returns JSON, never an HTML page. Validation failures also carry an errors object keyed by field name.

{
  "error": "Unauthorized. A valid API token is required.",
  "code": "unauthorized",
  "resolution": "Send the token in the Authorization header, for example `Authorization: Bearer <token>`. Create and manage tokens at https://app.getleal.com/api_tokens.",
  "documentation_url": "https://app.getleal.com/docs/api.html"
}

• 401 The API token is missing or invalid.
• 404 The record does not exist, or your token cannot reach that store.
• 422 The request was understood but rejected, usually a validation failure.
• 429 You exceeded the rate limit. Check Retry-After.

Rate limits

The API allows 300 requests per minute per API token. Unauthenticated requests are counted per IP address. Every response reports where you are, so a client can slow down before it is blocked:

RateLimit-Limit: 300
RateLimit-Remaining: 297
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Going over the limit returns 429 with a Retry-After header, in seconds, and a JSON body whose code is rate_limited. Wait for that long and retry. If you need a higher limit, get in touch.

Webhooks

Subscribe a URL to an event and Leal will POST to it, so you do not have to poll. Subscriptions belong to a store.

curl -X POST \
  https://app.getleal.com/api/v1/accounts/1/webhook_subscriptions \
  -H "Authorization: Bearer $LEAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event": "customer_card.stamped", "target_url": "https://example.com/hooks/leal"}'

Delete a subscription with DELETE on /accounts/:account_id/webhook_subscriptions/:id. The API reference lists the events you can subscribe to.

No code automation

You do not have to write code to connect Leal. The Zapier integration covers the common flows, and the point of sale integrations add stamps automatically when a customer pays.