Skip to main content
GET
Look up a verified identity by pairwise reference

Authorizations

X-API-Key
string
header
required

Path Parameters

principal_ref
string
required

Response

Response

Body for GET /identities/principals/{principal_ref}.

Strictly scoped to the calling organization: only links it covered with its own sessions are listed, and no PII beyond what the organization itself submitted is echoed — display_name repeats the verified name the list row already returns to the same caller, nothing more.

principal_ref
string
required

The queried pairwise principal reference.

verification_state
enum<string>
required

CURRENT, EXPIRED (re-verify before minting), or SUPERSEDED.

Available options:
CURRENT,
EXPIRED,
SUPERSEDED
display_name
string | null

The verified name, as the latest snapshot recorded it — the same value the list row carries. Null when every snapshot has been superseded. Mask it in shared surfaces; the API returns what the organization itself submitted.

verified_at
string<date-time> | null

When the latest verification was recorded.

expires_at
string<date-time> | null

When the latest verification expires.

active_keys
string[]

Dotted keys of the identity attributes the latest verification can attest to (e.g. user.email.hash) — the same vocabulary credential disclosure paths use.

verification_level
integer | null

Verification level derived from active_keys; null when the attested attributes are insufficient for any defined level.

businesses
IdentityBusinessLinkResponse (v1) · object[]

Businesses this organization holds covered operator links for, each with its pairwise ref and link status.

submissions
IdentitySubmissionHistoryItemResponse (v1) · object[]

This organization's verification attempts of the person, newest first — every submission whose evaluation ran against the same national id, whatever the outcome.

credential_activity
IdentityCredentialActivityResponse (v1) · object | null

Summary of this organization's recent credential mints for the person.

verification_history
IdentityVerificationHistoryItemResponse (v1) · object[]

Superseded verifications, newest first — when the person was verified before and when each verification was replaced. Dates only; superseded identity fields are never re-disclosed.