# Business API reference

> Read-only REST access to your own business's guest list, visit feed and retention metrics. Key from the panel, phones masked (KVKK).

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](https://api.sadakio.com/api/v1/openapi.yaml)

Today's surface is read only: you pull your data, no call changes anything. Write endpoints are on the [roadmap](/en/docs/yol-haritasi).

## 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"
```

```json
{"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`.

```json
{"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.