frontkiosk API

Read your visitor log and check people in and out from your own systems. Plain REST and JSON, with one API key per integration.

API access

API access is not included in the Lifetime or Monthly plans we sell today. It keeps working for organizations that bought our earlier plan with API access, which is no longer sold. To ask about API access for your organization, email hello@frontkiosk.net.

If your organization has API access, create keys in your dashboard under Settings, in the API keys section. Base URL:

https://frontkiosk.net/api/v1

Authentication

Send your key as a Bearer token on every request. Keys start with fk_live_. A key belongs to one organization and can see all of its locations.

curl https://frontkiosk.net/api/v1/me \
  -H "Authorization: Bearer fk_live_YOUR_KEY"

We only show a key once, when you create it, and we store only a hash of it. Keep keys on your server, never in a web page or app. If one leaks, revoke it in Settings: it stops working right away.

Errors

Errors use normal HTTP status codes and a JSON body:

{
  "error": {
    "type": "invalid_request",
    "message": "location_id is required",
    "param": "location_id"
  }
}

Status	type	Meaning
400	`invalid_request`	A parameter is missing or wrong. `param` names it when we can.
401	`authentication_required`, `invalid_api_key`	No key, or the key is wrong or revoked.
402	`plan_required`	This organization’s plan doesn’t include API access.
404	`not_found`	No such visit, location or endpoint in this organization.
409	`invalid_state`	For example, checking out someone who hasn't checked in.
415	`invalid_request`	Send JSON with `Content-Type: application/json`.
429	`rate_limited`	Too many requests. Wait for `Retry-After` seconds.
500	`api_error`	Something went wrong on our side. Retry later.

Rate limits

Each key can make 120 requests per minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Over the limit you get 429 with a Retry-After header.

Pagination

List endpoints return {"object": "list", "data": [...]}. The visits list also accepts limit (1–500, default 100) and offset, and returns total, has_more and next_offset.

The visit object

{
  "id": "6f0c1d1e-0b7a-4c6e-9d43-1f2a3b4c5d6e",
  "object": "visit",
  "status": "on_site",            // expected | on_site | signed_out | cancelled
  "location_id": "2a9e...",
  "location_name": "Brooklyn HQ",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "email": "ada@example.com",
  "phone": "",
  "type": "Guest",                // Guest | Contractor | Interview | Delivery
  "reason": "Interview",
  "host_id": "8c1b...",
  "host_name": "Grace Hopper",
  "policy_signed": false,
  "has_photo": false,
  "expected_at": null,            // set for pre-registered visits
  "signed_in_at": "2026-10-06T13:02:11.000Z",
  "signed_out_at": null,
  "signed_out_by": null           // kiosk | qr | admin | api ...
}

All times are ISO 8601 in UTC.

Check your key

GET/api/v1/me

curl https://frontkiosk.net/api/v1/me -H "Authorization: Bearer $FK_KEY"

{ "object": "api_key", "name": "HR system", "prefix": "fk_live_AbCd",
  "organization": { "id": "...", "name": "Northwind Studio" } }

List locations

GET/api/v1/locations

curl https://frontkiosk.net/api/v1/locations -H "Authorization: Bearer $FK_KEY"

{ "object": "list", "data": [
  { "id": "2a9e...", "object": "location", "name": "Brooklyn HQ", "slug": "brooklyn-hq",
    "time_zone": "America/New_York", "address": "", "created_at": "2026-09-01T14:00:00.000Z" } ] }

List hosts

GET/api/v1/hosts

Query	Description
`location`	Optional. Only hosts at this location id.

curl "https://frontkiosk.net/api/v1/hosts?location=2a9e..." -H "Authorization: Bearer $FK_KEY"

List visits

GET/api/v1/visits

Newest first. Expected (pre-registered) visits are listed only with status=expected, ordered by expected_at.

Query	Description
`location`	Location id.
`from`, `to`	`YYYY-MM-DD` (a day in the location's time zone, inclusive) or an ISO 8601 timestamp. Filters by sign-in time (or `expected_at`).
`status`	`all` (default: on site and signed out), `on_site`, `signed_out` or `expected`.
`q`	Text search over name, company, email, phone, host and reason.
`limit`, `offset`	Paging. `limit` 1–500, default 100.

# Everyone on site right now
curl "https://frontkiosk.net/api/v1/visits?status=on_site" -H "Authorization: Bearer $FK_KEY"

# Last week's visits at one location
curl "https://frontkiosk.net/api/v1/visits?location=2a9e...&from=2026-09-28&to=2026-10-04&limit=500" \
  -H "Authorization: Bearer $FK_KEY"

Get a visit

GET/api/v1/visits/{id}

curl https://frontkiosk.net/api/v1/visits/6f0c1d1e-... -H "Authorization: Bearer $FK_KEY"

Create a visit

POST/api/v1/visits

Check someone in right now (default), or pre-register a guest you're expecting with "status": "expected". Checking in sends the host's arrival email and your location webhook, just like the kiosk.

Field	Description
`location_id`	Required.
`name`	Required. Visitor's full name.
`host_id`	Optional. A host at that location (see List hosts).
`company`, `email`, `phone`, `reason`	Optional.
`type`	`Guest` (default), `Contractor`, `Interview` or `Delivery`.
`status`	`on_site` (default: check in now) or `expected` (pre-register).
`expected_at`	Optional, for `expected`. ISO 8601 time you expect them.

# Pre-register tomorrow's interview
curl https://frontkiosk.net/api/v1/visits \
  -H "Authorization: Bearer $FK_KEY" -H "Content-Type: application/json" \
  -d '{"location_id":"2a9e...","name":"Ada Lovelace","company":"Analytical Engines",
       "host_id":"8c1b...","type":"Interview","status":"expected",
       "expected_at":"2026-10-07T14:00:00Z"}'

# Check someone in now
curl https://frontkiosk.net/api/v1/visits \
  -H "Authorization: Bearer $FK_KEY" -H "Content-Type: application/json" \
  -d '{"location_id":"2a9e...","name":"Sam Courier","type":"Delivery"}'

Returns 201 with the new visit.

Check in an expected visitor

POST/api/v1/visits/{id}/check-in

Turns a pre-registration into an on-site visit (new id, status: "on_site") and alerts the host. Calling it again returns the same visit with already_checked_in: true.

curl -X POST https://frontkiosk.net/api/v1/visits/6f0c1d1e-.../check-in -H "Authorization: Bearer $FK_KEY"

Check out

POST/api/v1/visits/{id}/check-out

Signs the visitor out (signed_out_by: "api"). Safe to repeat: a second call returns already_checked_out: true.

curl -X POST https://frontkiosk.net/api/v1/visits/6f0c1d1e-.../check-out -H "Authorization: Bearer $FK_KEY"

Cancel a pre-registration

DELETE/api/v1/visits/{id}

Only for visits that are still expected. Returns the visit with status: "cancelled".

curl -X DELETE https://frontkiosk.net/api/v1/visits/6f0c1d1e-... -H "Authorization: Bearer $FK_KEY"