# Dokaa API

Public read-only API to access your Dokaa data (reviews, shops, analytics)
and build your own dashboards.

## Conventions
- **Authentication**: every request must include your API key:
  `Authorization: Bearer dk_...`
- **Versioning**: the major version is in the URL (`/v1`). Within v1, changes
  are strictly additive: your integration MUST ignore unknown fields.
- **Dates**: ISO 8601, UTC. Date filters are inclusive.
- **Pagination**: cursor-based. Pass `cursor` from the previous response's
  `pagination.next_cursor` to fetch the next page.
- **Errors**: RFC 9457 (Problem Details), `Content-Type: application/problem+json`.

## Contents

- [Shops](#shops) – 1 endpoint
- [Reviews](#reviews) – 1 endpoint
- [Analytics](#analytics) – 4 endpoints
- [Missed calls](#missed-calls) – 1 endpoint
- [Contacts](#contacts) – 1 endpoint
- [Campaigns](#campaigns) – 1 endpoint
- [Wheel games](#wheel-games) – 1 endpoint
- [Audiences](#audiences) – 1 endpoint
- [Google interactions](#google-interactions) – 1 endpoint
- [Competitors](#competitors) – 3 endpoints
- [Keyword tracking](#keyword-tracking) – 3 endpoints
- [Google posts](#google-posts) – 4 endpoints

## Shops

The establishments accessible with your API key. `GET /shops` is the
entry point of every integration: it lists your perimeter and gives you
the `id` values accepted as `shop_id` by all the other endpoints.

A key created for a single shop sees one entry here; a group key sees
every shop of the group, including shops that join the group later.

- [`GET /shops`](/docs/api/shops/listshops/) – List your shops

## Reviews

Customer reviews across every connected platform: Google, TripAdvisor,
Deliveroo, Uber Eats, TheFork, plus the satisfaction feedback collected
by Dokaa itself (`platform: dokaa`).

Use `/reviews` for the raw list (ratings, comments, replies, semantic
tags) and `/analytics/reviews` when you only need counts, averages and
distributions: the aggregates are computed server-side and cost one
call instead of a full pagination. One nuance: the analytics cover
external platforms only, while the list also includes Dokaa feedback.

- [`GET /reviews`](/docs/api/reviews/listreviews/) – List reviews

## Analytics

Precomputed aggregates, one call each: `/summary` for the cross-feature
KPIs of a shop, `/analytics/reviews` for review totals and star
distributions, `/analytics/feedbacks` for CSAT and NPS, and
`/analytics/contacts` for the contact base.

Prefer these endpoints over paginating list endpoints whenever you
only need figures: one call, server-side numbers.

- [`GET /summary`](/docs/api/analytics/getsummary/) – KPI summary
- [`GET /analytics/reviews`](/docs/api/analytics/getreviewanalytics/) – Review analytics
- [`GET /analytics/feedbacks`](/docs/api/analytics/getfeedbackanalytics/) – Satisfaction survey analytics (CSAT and NPS)
- [`GET /analytics/contacts`](/docs/api/analytics/getcontactanalytics/) – Contact base analytics

## Missed calls

Statistics on the calls your shops missed, detected by Dokaa, with the
automatic SMS follow-up figures: calls, SMS sent, delivered and blocked,
evolution over time and comparison with the previous period. Test calls
from the configuration screen are excluded. The `/summary` endpoint
carries the matching headline figures.

- [`GET /analytics/missed-calls`](/docs/api/missed-calls/getmissedcallanalytics/) – Missed call analytics

## Contacts

The customer base of your shops: identity, visits, orders, SMS and
email opt-in status, and loyalty membership. Contacts are unique per
shop and phone number, and `sources` traces every channel that
collected them.

`/contacts` returns the raw rows (built for exports and CRM syncs);
`/analytics/contacts` returns the reachability and loyalty counters.
These endpoints expose personal data: scope the keys you distribute
accordingly.

- [`GET /contacts`](/docs/api/contacts/listcontacts/) – List contacts

## Campaigns

The SMS marketing campaigns of your shops, with their audience size,
per-message content and sending status. One campaign can carry several
scheduled messages; the whole timeline comes in a single row.

- [`GET /campaigns`](/docs/api/campaigns/listcampaigns/) – List SMS campaigns

## Wheel games

Analytics on the gift wheel of your shops: participations, validations,
gifts claimed, CTA clicks and marketing opt-ins with their rates, the
breakdown of the gifts won, evolution over time and comparison with the
previous period.

- [`GET /analytics/wheel-games`](/docs/api/wheel-games/getwheelanalytics/) – Gift wheel analytics

## Audiences

The contact segments and lists your shops defined in Dokaa (dynamic
audiences and static lists), with their current contact count and last
recomputation time. Useful to mirror your targeting structure in an
external tool.

- [`GET /audiences`](/docs/api/audiences/listaudiences/) – List audiences

## Google interactions

Daily Google Business Profile metrics per shop: profile views on
Search and Maps (mobile and desktop), website clicks, calls and
direction requests. One row per shop per day, refreshed nightly from
Google, which may lag up to 24 hours.

- [`GET /google-interactions`](/docs/api/google-interactions/listgoogleinteractions/) – List daily Google Business Profile metrics

## Competitors

The competitor tracking of your shops, computed from daily Google
snapshots. `/competitors` returns the panel (target, tracked competitors,
groups); `/competitors/positioning` ranks the shop in its panel on a
given day; `/competitors/evolution` follows reviews gained, rating deltas
and share of voice over a period.

- [`GET /competitors`](/docs/api/competitors/getcompetitors/) – Competitor tracking setup of a shop
- [`GET /competitors/positioning`](/docs/api/competitors/getcompetitorpositioning/) – Competitor positioning of a shop
- [`GET /competitors/evolution`](/docs/api/competitors/getcompetitorevolution/) – Competitor evolution over a period

## Keyword tracking

The Google Maps ranking of your shops on their tracked keywords,
scanned on a geographic grid. `/keyword-tracking` returns the setup
(keywords, scanned points, subscription state);
`/keyword-rankings/summary` returns the per-keyword results of a day
(average rank, center rank, top 3 and top 7 share, coverage);
`/keyword-rankings/trend` follows one keyword over a period.

- [`GET /keyword-tracking`](/docs/api/keyword-tracking/getkeywordtracking/) – Keyword tracking setup of a shop
- [`GET /keyword-rankings/summary`](/docs/api/keyword-tracking/getkeywordrankingsummary/) – Keyword ranking summary of a day
- [`GET /keyword-rankings/trend`](/docs/api/keyword-tracking/getkeywordrankingtrend/) – Keyword ranking trend over a period

## Google posts

The Google Business Profile posts of your shops: content, medias,
call-to-action, event and offer details, and publication status. Posts
created through Dokaa and posts fetched from Google are both included,
told apart by `source`. Grouped posts (one template published across
several shops) have their own endpoints under `/google-post-groups`,
including the list of shops eligible to receive one.

- [`GET /google-posts`](/docs/api/google-posts/listgoogleposts/) – List Google posts
- [`GET /google-post-groups`](/docs/api/google-posts/listgooglepostgroups/) – List grouped Google posts
- [`GET /google-post-groups/eligible-shops`](/docs/api/google-posts/listeligibleshops/) – List shops eligible for grouped posts
- [`GET /google-post-groups/{batch_id}`](/docs/api/google-posts/getgooglepostgroup/) – Detail of a grouped Google post