canonical: https://jentic.com/apis/getleal.com/getleal # Getleal Leal Loyalty API Jentic publishes the only available OpenAPI specification for the Leal Loyalty API, keeping it validated and agent-ready. Leal is a Latin American loyalty programme platform; the v1 REST API exposes 30 endpoints covering stores, locations, customers, customer cards, loyalty cards, posters, and rewards. Agents can stamp and redeem customer loyalty cards, manage rewards catalogues, and onboard customers and locations under a Leal account. Authentication is HTTP Bearer using a per-account access token. ## For AI agents Stamp and redeem Leal loyalty cards, manage customers, locations, and rewards across a merchant's loyalty programme. ## Scope Does not handle payments, gift card balances, or marketing email delivery - use for loyalty stamp, redemption, and rewards management only. ## Capabilities - Create, list, and update loyalty card templates that customers earn stamps against - Stamp a customer's loyalty card via POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/stamp` - Redeem a customer's loyalty card via POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/redeem` - Onboard new customers and update their profile data through the customers endpoints - Manage merchant locations including create, fetch, update, and delete operations - Maintain a rewards catalogue with create, fetch, update, and delete operations on `/accounts/{account_id}/rewards` ## Use cases ### POS-Triggered Loyalty Stamping Connect a point-of-sale system to Leal so that completing a purchase automatically stamps the customer's loyalty card. The integration calls POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/stamp` at checkout. Replaces manual app-based stamping at the counter and reduces friction for repeat customers. Example prompt: Call POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{card_id}/stamp` at checkout and confirm the response shows the updated stamp count. ### Reward Redemption Flow Allow staff to redeem a completed loyalty card by calling POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/redeem` from a tablet at the counter. The integration first reads the customer's cards via GET `/accounts/{account_id}/customers/{customer_id}/customer_cards` to verify the card is full. Removes the need to fall back to the Leal admin app. Example prompt: Call GET `/accounts/{account_id}/customers/{customer_id}/customer_cards` to find a redeemable card, then POST to its redeem endpoint. ### Multi-Location Rewards Catalogue Management Maintain the rewards catalogue and merchant locations programmatically as the merchant scales. The integration calls the `/accounts/{account_id}/rewards` and `/accounts/{account_id}/locations` endpoints to add, update, or retire entries. Useful for chains that change rewards seasonally. Example prompt: Call POST `/accounts/{account_id}/rewards` with name='Free Coffee' and the required cost, then PATCH the entry once a quarter to refresh seasonal rewards. ### AI Agent Loyalty Concierge An AI agent acts as a loyalty concierge that creates customer profiles, stamps cards based on purchase webhooks, and redeems rewards on demand. The agent uses Jentic's intent search rather than reading Leal's docs directly, and Jentic stores the Bearer token out of context. Time-to-first-stamp drops from hours to minutes. Example prompt: Search Jentic for 'stamp a Leal loyalty card', load the schema, and stamp the customer card associated with the most recent purchase webhook. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/accounts/{account_id}/customers` | Create a customer | | POST | `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/stamp` | Stamp a customer's loyalty card | | POST | `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/redeem` | Redeem a customer's loyalty card | | GET | `/accounts/{account_id}/customers/{customer_id}/customer_cards` | List a customer's loyalty cards | | POST | `/accounts/{account_id}/rewards` | Create a reward in the catalogue | | POST | `/accounts/{account_id}/locations` | Create a merchant location | ## Key resources - **Customers** — List, create, fetch, and update customer profiles - **Customer Cards** — Inspect, stamp, and redeem the loyalty cards a customer is collecting - **Cards** — Manage loyalty card templates that customers earn stamps against - **Locations** — Create, fetch, update, and delete merchant locations - **Rewards** — Maintain the rewards catalogue available to customers - **Posters** — Manage promotional posters tied to a merchant account ## Why Jentic - **Setup:** Wiring Leal by hand means setting its bearer auth, threading the account id, customer id, and card id through the loyalty paths, and shaping stamp and redeem payloads yourself. Through Jentic you install once, import the Leal Loyalty API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Leal puts the account id in the URL path (`/accounts/{account_id}/...`), so a rule can pin your agent to one account: it stamps and redeems cards and manages rewards and locations there and nothing else. You choose the operations it may call, so creating a location is not included unless you add it. - **Credential handling:** Your Leal token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'stamp a loyalty card' or 'redeem a reward', and Jentic returns the matching Leal operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Loyalzoo API** — SMB loyalty programme platform with similar stamp-and-redeem mechanics - **Square API** — Square's payments and POS platform pairs with a dedicated loyalty back-end - **Klaviyo API** — Email and SMS marketing alongside a loyalty programme to follow up after redemptions ## FAQ ### Why is there no official OpenAPI spec for the Leal Loyalty API? Leal does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Leal Loyalty API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Leal Loyalty API use? Leal uses HTTP Bearer authentication with an API token issued per merchant account. Jentic stores the Bearer token in its encrypted vault and injects the Authorization header on every call so the merchant token never enters the agent context. ### Can I stamp a customer's loyalty card with the Leal API? Yes. Call POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/stamp` where the path includes the merchant account, customer, and the specific customer-card the stamp should attach to. The response includes the updated stamp count and completion status. ### What are the rate limits for the Leal Loyalty API? Leal does not document explicit rate limits in the spec. For POS workloads, plan for sustained throughput around 5 requests per second per account and back off when 429 responses appear; the response body usually carries a retry hint. ### How do I redeem a loyalty card through Jentic? Search Jentic for 'redeem a Leal loyalty card', load the schema for POST `/accounts/{account_id}/customers/{customer_id}/customer_cards/{id}/redeem`, and execute with the account, customer, and card ids. Jentic injects the Bearer token automatically. ### Can I manage merchant locations through the Leal API? Yes. The `/accounts/{account_id}/locations` endpoints support listing, creating, fetching, updating, and deleting merchant locations so that multi-store loyalty programmes can be managed without the admin UI. ### Can I limit what my agent is allowed to do with the Leal Loyalty API? Yes. Because Jentic One is self-hosted, your own rules decide which Leal operations and credentials the agent may use. Since Leal puts the account id in the URL path (`/accounts/{account_id}/...`), you can pin the agent to a single merchant account and grant only the operations you want, such as stamping and redeeming customer cards while excluding creating locations or editing the rewards catalogue. The agent can call only the operations you allow, and your Leal token stays with your Jentic One instance rather than the agent's context.