Business API reference

Base URL: https://api.sadakio.com/api/v1 Auth: Authorization: Bearer sk_YOUR_KEY — keys come from Settings → API in the panel and are bound to exactly one business. Machine contract: api/v1/openapi.yaml

Today's surface is read only: you pull your data, no call changes anything. Write endpoints are on the roadmap.

GET /guests

Your guest list, cursor-paginated by ascending id.

Parameter	Meaning
`search`	Name substring, or phone tail when 4+ digits are given
`updated_since`	ISO 8601: visited OR newly joined since this moment
`cursor`, `limit`	Pagination, `limit` capped at 100

updated_since is designed for incremental sync: a brand-new guest who has not visited yet still matches, so a nightly sync never misses anyone.

curl "https://api.sadakio.com/api/v1/guests?updated_since=2026-09-20T00:00:00Z" \
  -H "Authorization: Bearer sk_YOUR_KEY"

{"data": [{"id": 184, "name": "Elif T.", "masked_phone": "+•••••••4579",
           "email": null, "joined_at": "2026-06-01T09:12:00Z",
           "visits_count": 12, "last_visit": "2026-09-16T08:31:00Z",
           "has_birth_date": true, "opt_in": true, "lang": "tr"}],
 "next_cursor": null}

GET /guests/{id}

One guest with their cards: program type, stamps, points, cashback balance, level points and rewards earned.

GET /visits

The visit feed: earns, redeems and reversals on one timeline. Date filters since and until, pagination with cursor and limit.

{"data": [{"id": 5012, "card_id": 77, "type": "earn", "amount": 1,
           "note": null, "staff_id": 3,
           "created_at": "2026-09-16T08:31:00Z", "reversed_at": null}],
 "next_cursor": 5012}

GET /stats/retention

The returning-guest summary. period is week, month or year: rolling 7, 30 and 365-day windows. Returns the number of guests who joined before the window and came back inside it, their visits, and with the optional avg_ticket a rough revenue equivalent. It is return analytics, not a revenue guarantee.

curl "https://api.sadakio.com/api/v1/stats/retention?period=month&avg_ticket=180" \
  -H "Authorization: Bearer sk_YOUR_KEY"

GET /openapi.yaml

The open OpenAPI 3.0 contract, no key required. A generator or an AI agent discovers the API in one fetch.

Data rules

Phones are masked in every response in the masked_phone field, only the last 4 digits are visible.
Data belongs only to the business the key is bound to. Another business's guest id answers 404.
Rate: 60 requests per second and 10,000 per day per key. Remaining quota in the X-RateLimit-Limit / Remaining / Reset headers.

This page as .md: /en/docs/api.md