What You Can Learn
Your developer can pull these into your analytics tool.
Authenticating
Send your API key in theX-API-Key header, as for every Baselayer request. See Authentication. The visits reads need the acceptance_visits:read permission.
Every read answers for the application your key belongs to: a sandbox key reads your sandbox application, and a production key reads your production application. You never pass an application ID.
Lists and Pages
Every list returns a bare JSON array, a page at a time.
Each page carries these headers:
Use
cursor to walk a long list: a page never skips or repeats a record when new visits arrive.
Dates and Time Zones
The visits list and the identity funnel take a date range:
The identity funnel reads the last 30 days when you send no dates, and refuses a range over 366 days with
422 date_range_too_large.
Freshness and Retries
Visits are rebuilt about once a minute, so a visit, its timeline and its decisions show a record about a minute after it is reported. When the acceptance data cannot be read for a moment, a read answers503 with a Retry-After header and this body. Wait that many seconds and send the request again.
type. message is for people to read.
List Your Visits
A visit is one visitor’s run of records at your site, from the browser and your server alike, until 30 minutes pass without one. Visits are newest first by default (sort=started_at, or sort=last_seen_at).
Filters take one value or several (identity_level=L2&identity_level=L3): presence_kind, presence_trust, identity_level, transport, state, outcome, agent_key_thumbprint, credential_id and credential_subject. Values of one filter match any of them, and different filters must all match.
presence is what is behind the visit now: kind (human, agent, crawler, automation or unknown) and trust, how strongly the evidence backs it, strongest first: credentialed, verified, declared, scored, unobserved and none. journey lists the pages a browser visit viewed, and is null for a visit with no page views.
credential.subject is the credential’s sub: the same site-specific customer ID your credential check sees, so you can match a visit to your customer. identity.subject is the same value. See Matching Customers.
Get One Visit
GET /acceptance/visits/{visit_id} returns the visit with two more members: identity, who the visitor is as far as the evidence goes, and detection, what browser detection made of it (null before any detection result).
Read a Visit’s Timeline
GET /acceptance/visits/{visit_id}/timeline lists what happened, oldest first (sort=timeline, sort_direction=asc; ties break on record_id). Each item’s kind says what it is:
Read a Visit’s Decisions
GET /acceptance/visits/{visit_id}/decisions lists every decision your KYA SDK made during the visit, newest first (sort=decided_at, sort_direction=desc; ties break on the decision’s ID), in full: the presence it ran on, the evidence, the policy rule that fired, the credential and Baselayer’s own check of the decision in integrity. Filter with step and outcome. This read needs the acceptance_decisions:read permission.
outcome is what the policy recommended: allow, challenge, step_up or block. merchant_outcome is what your site then did, when the SDK could observe it. integrity.is_policy_hash_mismatch is true when the SDK ran a policy that differs from the version it named.
Count Visits by Identity
GET /acceptance/visits/identity_funnel counts the visits that started in the range by how far their identity got, each visit counted once, at its stage now:
A visit that detection only scored counts as
anonymous here. This is separate from a visit’s funnel_stage, which is how far it got toward a purchase.
Reading Identity Levels
A visit’sidentity_level, and the identity_level filter, run from L1 to L3:
A KYA credential with
verification_level 1, 2 or 3 gives the visit identity_level L1, L2 or L3. identity_level is null for a person, an unknown visitor or a claim nothing corroborated.