Read your data with the API
The Whence API lets your own tools (a spreadsheet, a data warehouse, a dashboard) read your visits, the problems Whence detected and your daily reports. A key reads only: it cannot change anything in Whence.
API keys come with the Decide plan. On another plan, Settings, API keys shows Available on Decide.
Step 1: Create a key
- Open Settings, then API keys.
- Give the key a name of at least 3 characters (for example “My data warehouse”).
- Under What the key can read, tick at least one item: Visits and recordings, Detected problems, Daily reports, Order amounts, Customer details, Ad campaigns. You can only tick what you can see yourself.
- Click Create key.
The key is shown once. Copy it then (Copy key), and click I have saved it. Whence keeps only a fingerprint of the key: a lost key cannot be shown again. Revoke it and create another.
Only people with the Connections right can create or revoke keys. A key never reads more than the person who created it can see, and it expires after a year. The list shows when each key was last used and when it expires.
Step 2: Revoke a key
Click Revoke next to the key, then Revoke key. Apps using this key stop working at once.
Call the API
Send the key in the x-api-key header, to the address shown on the API keys page. If the key covers all your stores and you have more than one, name the store in the x-site-id header. Answers are JSON, and a key can make 120 requests a minute.
| Request | What it returns |
|---|---|
GET /v1/sites | Your stores. |
GET /v1/sessions | Visits, newest first, 50 at a time (up to 100 with limit), with next_cursor for the next page. |
GET /v1/sessions/{id} | One visit. Add ?include=events to get its recording. |
GET /v1/issues | The problems Whence detected, up to 100. |
GET /v1/reports | The last 30 daily reports. |
Order amounts, customer details and campaign names come back empty unless the key has that permission and the person who created it still has the matching right.
Common answers
- 403, “The API is available on the Decide plan.”: the account is no longer on Decide.
- 429, “rate limit exceeded”: more than 120 requests in a minute. Wait and try again; the
X-RateLimit-Resetheader says when. - 404, “unknown API route”: the address does not match one of the five requests above.