Skip to content
Leat Help Center

Build a custom integration with the Leat API

Need an API key for a system that's in the marketplace, like a till, kiosk, webshop or email tool? Don't create a private app. Install that integration and create the key there. See Where to find your API key or access token, and for a till Create a register and access token for each till.

Leat has a public REST API that works with the same data the dashboard does: contacts, points, tiers, rewards, vouchers, gift cards, orders, shops and more. The full reference lives at docs.leat.com/v3.

If none of the ready-made integrations in the marketplace does what you need, this is how you build it yourself, or hand it to a developer to build.

What you can build with it

Things teams commonly build on the API:

  • A till or point of sale that isn't on our integrations list, so staff can find a contact and award points at checkout.
  • A self-service kiosk where contacts identify themselves and redeem a reward.
  • An order-at-table or ordering app that applies promotions and vouchers.
  • A website or webshop that shows a contact their balance and lets them claim rewards.
  • Internal tooling: creating contacts from a system you already run, or pulling loyalty transactions into your own reporting.

The documentation has step-by-step tutorials for a point of sale, a kiosk and order-at-table, under Tutorials.

Create a private app and a personal access token

Every request is authenticated with a personal access token, and a token belongs to a private app in your account:

  1. In the dashboard, go to Apps, then Integrations.
  2. On the Marketplace page, click Create private app in the top right.
  3. Name it after the system you're connecting, then click Create.
  4. Open the Auth tab and click Create personal access token.
  5. Pick an expiration: never, 1 month, 1 year, 2 years or 3 years.
  6. Copy the token straight away. It's shown once and can't be retrieved later.

Give every system you connect its own private app. You can then see what is connected, and rotating or deleting one token doesn't break anything else. On the Auth tab you can rotate a token later, either letting the old one keep working for 14 days or expiring it immediately.

Make your first request

Send the token as a bearer token in the Authorization header:

curl https://api.leat.com/api/v3/oauth/clients/contacts \
  -H "Authorization: Bearer {{ access_token }}"

Every endpoint sits under https://api.leat.com/api/v3/oauth/clients/.

What the API covers

The reference groups the endpoints by subject:

  • Contacts, their attributes, identifiers, subscriptions and verification.
  • The loyalty program: credit receptions, loyalty transactions, tiers, units and perks.
  • Rewards, collectable rewards, reward receptions, promotions, vouchers and referrals.
  • Gift card programs, gift cards, gift card transactions and prepaid transactions.
  • Orders, order returns, products, categories, shops, POS transactions, visits and bookings.
  • Shifts, shift types and shift teams.
  • Forms, automations, custom attributes, the brand kit, the contacts portal and portal sessions.

Get notified with webhooks

Instead of polling the API for changes, let us call you. Open your private app, go to the Webhooks tab and click New webhook: choose the event, give it a name and enter the URL on your side.

Events include contact_created, contact_updated, tier_reached, credit_reception_created, giftcard_transaction_created, voucher_redeemed, reward_redeemed, order_created, visit_created, form_submission_completed and referral_completed.

A webhook created there always sends an array of events, up to 100 per request, and every request is signed. Build for that from the start. Webhooks: send events from Leat to your own system has the full list of events, the payload, how to check the signature, and what happens when your endpoint doesn't answer.

Use a webhook subscription rather than the Webhook action in an automation. The automation webhook isn't signed or retried.

Test without messing up your data

There's no separate sandbox: you test against the live environment. Create a separate account for testing so test data stays out of your real dashboard, and don't use real email addresses of contacts while you do it. If automations or campaigns are active in that account, those emails actually go out.

Errors

A request that fails comes back with status code 400 and the same shape every time:

{
    "message": "<message>",
    "code": <code>,
    "status_code": 400
}

Each endpoint in the reference lists the errors it can return, and the Error handling page has the complete list in one place.

A head start in PHP

If you're building in PHP, there's an SDK you can pull in with composer require piggy/piggy-php-sdk, so you don't have to write the HTTP layer yourself.

If you're on the Register API

The older Register API is being phased out. Personal access tokens now work on the v3 routes too, so there's no longer a reason to have a separate one. Existing Register API endpoints keep working for now, but build anything new against v3 and plan to move what you already have.

Getting help

Email partners@leat.com with questions about the API. We usually reply within a day, and we can also add you to a Slack channel with the development team, which is normally faster during business hours. Ask for it by email.

Back to the help center