---
title: "Look up a verified identity by pairwise reference"
method: GET
path: "/identities/{principal_ref}"
tags: ["Identities"]
---

# Look up a verified identity by pairwise reference

`GET /identities/{principal_ref}`

Returns the verification state, verified-attribute keys, verification level, and covered business links for a `principal_ref` issued to your organization. References issued to other organizations and unknown references are indistinguishable `404`s.

## Path parameters

- `principal_ref` string, required

## Response `200`

Response

- V1IdentityStatusResponse — Body for ``GET /identities/{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 (none is).
  - `principal_ref` string, required — The queried pairwise principal reference.
  - `verification_state` 'CURRENT' | 'EXPIRED' | 'SUPERSEDED', required — Verification state of an identity, as seen by the referencing organization. CURRENT: an unexpired verification exists and credentials can be minted. EXPIRED: the verification's validity window has lapsed — re-verify before minting. SUPERSEDED: no active verification record remains; a new submission is required.
  - `verified_at` string, date-time, nullable — When the latest verification was recorded.
  - `expires_at` string, date-time, nullable — 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, nullable — Verification level derived from active_keys; null when the attested attributes are insufficient for any defined level.
  - `businesses` V1IdentityBusinessLinkResponse[] — Businesses this organization holds covered operator links for, each with its pairwise ref and link status.
    - `business_ref` string, required — Pairwise reference to the linked business.
    - `status` 'VERIFIED' | 'UNDER_REVIEW' | 'REJECTED', required — Status of the link between a person (principal) and a business they operate. VERIFIED is earned by the full evidence recipe (TIN provided + IRS-matched + KYB-verified) or granted by manual review; UNDER_REVIEW is every automatic shortfall; REJECTED is a manual refusal. A rejected link is immutable — a later submission evaluates the pair fresh.

## Other responses

- `404` — The principal_ref is unknown or was issued to another organization — the two are indistinguishable.
- `422` — Validation Error

---

[API](https://skmtc.net/baselayer/apis/baselayer-api-service.md) · [All operations](https://skmtc.net/baselayer/apis/baselayer-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/baselayer/baselayer-api-service/versions/0cc89938bc26/schema)