Developers

API Documentation

A read-focused REST API over your guest data. Available on Scale and Enterprise plans.

Authentication

Create a token in the dashboard under API tokens, choosing only the scopes the integration needs. The token is shown once — we store only a hash, so we cannot recover it for you. Send it as a bearer token:

curl https://app.footfall.cloud/api/v1/me \
  -H "Authorization: Bearer ff_your_token_here"

Every response is scoped to the token's business. A record belonging to another business returns 404, never its contents.

Scopes

customers:readRead customer records
customers:writeCreate and update customers
leads:readRead leads
leads:writeCreate and update leads
sessions:readRead guest sessions
presence:readRead presence and footfall analytics
analytics:readRead aggregate analytics
campaigns:readRead campaigns and message history

Endpoints

GET/api/v1/meany

Confirm a token works, and see which business and scopes it carries.

GET/api/v1/customerscustomers:read

List customers, newest activity first. Filter with ?email=.

GET/api/v1/customers/{id}customers:read

One customer. Returns 404 for records outside your business.

GET/api/v1/leadsleads:read

List leads. Filter with ?status=new|engaged|converted|unsubscribed.

GET/api/v1/sessionssessions:read

Guest sessions in a window. Filter with ?location_id=.

GET/api/v1/presence/summarypresence:read

Footfall counts, capture rate, dwell, and a per-zone breakdown.

GET/api/v1/analytics/summaryanalytics:read

Session and customer totals, plus sessions by location.

GET/api/v1/campaignscampaigns:read

List campaigns with their trigger, channel and status.

Pagination

List endpoints take ?page= and ?page_size=(default 50, maximum 200) and return a pagination object alongside the data. Endpoints covering a period accept ?start= and ?end=as ISO-8601 timestamps, defaulting to the last 30 days.

{
  "data": [ … ],
  "pagination": { "page": 1, "page_size": 50, "total": 128, "pages": 3 }
}

Errors

401unauthorizedMissing, malformed, expired or revoked token.
403insufficient_scopeThe token is valid but lacks a required scope.
403plan_requiredAPI access is not included in this plan.
404not_foundNo such record in your business.
429—Rate limit exceeded.

Rate limits

Record endpoints allow 120 requests per minute; analytics and presence endpoints allow 60. Exceeding a limit returns 429 — back off and retry.