Check-ins

A check-in records a person entering, taking optional breaks, and exiting a site. Endpoints and schemas live under Checkins in the API Reference.

Scope

Person check-ins are nested under /checkins/people. Create, list, read, checkout, and break routes are site-scoped — siteId stays in the path because those operations act on one site at a time:

/sites/{siteId}/checkins/people/…

Search is not site-scoped. Use one endpoint and pass siteIds in the body:

POST /checkins/people/search

Query	siteIds in body
One site	[67890]
Several sites	[67890, 67891, …]
Every site your integration can access	omit, or []

Each result includes the siteId it belongs to.

Site access: every siteId is resolved against Spectro using your Bearer token. Locations your token cannot view are excluded; an unknown or unauthorized siteId returns 404. When siteIds is omitted, the search spans every site your token can view. Spectro location lists are not cached — each request re-checks access.

Lifecycle

Each transition is one API request:

No record

→

POST …/checkins

IN

From IN the next successful write moves the check-in along one of these paths (breaks are optional; checkout ends the visit).

Breaks (repeatable)

1. POST …/breaks/start ON BREAK
2. PUT …/breaks/end

   Returns to IN. The cycle can run again.

Checkout (terminal)

1. PATCH …/checkout OUT

   No further breaks or checkouts on this check-in.

status	Meaning
IN	Person is on site.
PENDING	Recorded but not yet admitted (clearance pending).
STOP	Entry blocked — compliance or clearance failed.
OUT	Checked out. No further breaks.

Note

PENDING is usually server-assigned while clearance is still pending (documents, host approval, induction). The platform moves the check-in to IN when cleared, or STOP if not.

This API’s create path does not run those checks — use status: "IN" for someone already on site. Treat PENDING as something you read on check-ins from other channels (Doorkeeper, Workforce). A PENDING check-in cannot check out until it is IN.

Source

entry.source and exit.source record which channel produced the event:

Value	Meaning
API	Created via this public API (always set on entry for your creates).
DOORKEEPER	Doorkeeper kiosk.
QR_CODE	Static QR scan.
WORKFORCE	Aware Workforce app.
MANUAL	Operator console.
OTHER	Other internal channel.

You do not send entry source on create. You may set exit.source on checkout. Search filters use the same enum — best-effort on legacy data.

Operations

Every check-in endpoint is documented under Checkins and Breaks. Use Scalar’s Try it panel for request samples.

People check-ins

All routes below live under /checkins/people. Breaks apply to people only.

GET

/sites/{siteId}/checkins/people/config

Different sites require different fields on create. Call this first and cache the result per siteId for a few minutes.

Creating, breaks, and checkout

POST

/sites/{siteId}/checkins/people

Creates a check-in with checkinId and status: “IN”. See Create checkin (CreateCheckinRequest). Send an Idempotency-Key — Idempotency.

POST

…/checkins/people/{checkinId}/breaks/start

Opens a break on the active check-in. One open break per check-in at a time.

POST

…/checkins/people/{checkinId}/breaks/end

Closes the active break. The breaks array on the check-in response is full history.

PATCH

…/checkins/people/{checkinId}

Moves the check-in to OUT and closes any active break in the same request.

Reading check-ins

GET

/sites/{siteId}/checkins/people

List person check-ins for a site, with pagination. Use search for filtered or multi-site queries.

GET

/sites/{siteId}/checkins/people/{checkinId}

Fetch a single check-in when you already have checkinId.

POST

/checkins/people/search

Filter and paginate person check-ins — see PeopleCheckinsSearchRequest. Pass siteIds to scope the query; omit it to search all accessible sites.

Idempotency keys

Operation	Idempotency-Key	Why
POST …/checkins/people	Recommended	A retried create must not produce two check-ins.
POST …/breaks/start	Recommended	A retried start must not open two breaks.
PATCH …/checkins/people/{checkinId}	Recommended	Prevents duplicate downstream notifications on checkout.
POST …/breaks/end	Optional	Re-end returns 409.
GET / POST …/search	N/A	Reads are safe to retry.

See Idempotency, Errors, and Rate limits.