> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Look up a verified identity by pairwise reference > 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. ## OpenAPI ````yaml /api-reference/openapi.json get /identities/principals/{principal_ref} openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /identities/principals/{principal_ref}: get: tags: - Identities summary: Look up a verified identity by pairwise reference description: >- 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. operationId: get_identity_status parameters: - name: principal_ref in: path required: true schema: type: string title: Principal Ref responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/v1.IdentityStatusResponse' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.IdentityStatusResponse' '404': description: >- The principal_ref is unknown or was issued to another organization — the two are indistinguishable. content: application/json: schema: $ref: '#/components/schemas/APIError' title: ResourceNotFound description: Could not locate the resource for the given URI. examples: - code: 1 message: Could not locate the resource for the given URI. metadata: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: v1.IdentityStatusResponse: description: |- 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. properties: principal_ref: description: The queried pairwise principal reference. title: Principal Ref type: string display_name: anyOf: - type: string - type: 'null' default: null description: >- 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. title: Display Name verification_state: $ref: '#/components/schemas/v1.IdentityVerificationState' description: CURRENT, EXPIRED (re-verify before minting), or SUPERSEDED. verified_at: anyOf: - format: date-time type: string - type: 'null' default: null description: When the latest verification was recorded. title: Verified At expires_at: anyOf: - format: date-time type: string - type: 'null' default: null description: When the latest verification expires. title: Expires At active_keys: description: >- Dotted keys of the identity attributes the latest verification can attest to (e.g. `user.email.hash`) — the same vocabulary credential disclosure paths use. items: type: string title: Active Keys type: array verification_level: anyOf: - type: integer - type: 'null' default: null description: >- Verification level derived from active_keys; null when the attested attributes are insufficient for any defined level. title: Verification Level businesses: description: >- Businesses this organization holds covered operator links for, each with its pairwise ref and link status. items: $ref: '#/components/schemas/v1.IdentityBusinessLinkResponse' title: Businesses type: array submissions: description: >- This organization's verification attempts of the person, newest first — every submission whose evaluation ran against the same national id, whatever the outcome. items: $ref: '#/components/schemas/v1.IdentitySubmissionHistoryItemResponse' title: Submissions type: array credential_activity: anyOf: - $ref: '#/components/schemas/v1.IdentityCredentialActivityResponse' - type: 'null' default: null description: >- Summary of this organization's recent credential mints for the person. verification_history: description: >- 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. items: $ref: '#/components/schemas/v1.IdentityVerificationHistoryItemResponse' title: Verification History type: array required: - principal_ref - verification_state title: IdentityStatusResponse (v1) type: object APIError: properties: code: type: integer title: Code message: type: string title: Message uri: anyOf: - type: string - type: 'null' title: Uri metadata: additionalProperties: true type: object title: Metadata type: object required: - code - message title: APIError description: >- APIError is a Pydantic model for standardizing error responses from the API. This class is used internally by APIException for JSON serialization. Users should typically work with APIException directly in exception catalogs. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError v1.IdentityVerificationState: description: |- 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. enum: - CURRENT - EXPIRED - SUPERSEDED title: IdentityVerificationState type: string v1.IdentityBusinessLinkResponse: description: |- One business the calling organization holds a covered operator link for. properties: business_ref: description: Pairwise reference to the linked business. title: Business Ref type: string status: $ref: '#/components/schemas/v1.BusinessOperatorLinkStatus' description: Current status of the operator link. required: - business_ref - status title: IdentityBusinessLinkResponse (v1) type: object v1.IdentitySubmissionHistoryItemResponse: description: |- One verification attempt in a profile's submission history. The same submission the polling route reports, reduced to the row a history timeline renders — refs and verification results live on the profile itself, not repeated per attempt. properties: submission_id: description: >- Unique id of the submission — resolvable via `GET /identity_submissions/{submission_id}`. format: uuid title: Submission Id type: string state: $ref: '#/components/schemas/v1.ResumableWorkflowState' description: Lifecycle state of the verification workflow. verdict: anyOf: - $ref: '#/components/schemas/v1.OnboardingVerdict' - type: 'null' default: null description: Resolved onboarding verdict; null until completion. reference_id: anyOf: - type: string - type: 'null' default: null description: Caller-supplied correlation id. title: Reference Id created_at: description: When the submission was accepted. format: date-time title: Created At type: string completed_at: anyOf: - format: date-time type: string - type: 'null' default: null description: When the workflow reached a terminal state. title: Completed At terminal_reason: anyOf: - $ref: '#/components/schemas/v1.IdentitySubmissionTerminalReasonResponse' - type: 'null' default: null description: >- Typed state and detail when the workflow ended in FAILED or CANCELLED; null otherwise. required: - submission_id - state - created_at title: IdentitySubmissionHistoryItemResponse (v1) type: object v1.IdentityCredentialActivityResponse: description: |- A profile's recent credential-minting summary. A summary only — the full issuance log stays on the credentials listing route, filterable by the same pairwise reference. properties: credentials_minted_30d: description: >- Credentials this organization minted for the person in the last 30 days, counting business credentials they acted for. title: Credentials Minted 30D type: integer last_minted_at: anyOf: - format: date-time type: string - type: 'null' default: null description: >- When this organization last minted a credential for the person; null when it never has. title: Last Minted At required: - credentials_minted_30d title: IdentityCredentialActivityResponse (v1) type: object v1.IdentityVerificationHistoryItemResponse: description: |- One superseded verification in a profile's lineage. Dates only: a superseded snapshot's identity fields are history the directory never re-discloses — the row exists so the profile can show when the person was verified before and when each verification was replaced. properties: verified_at: description: When this verification was recorded. format: date-time title: Verified At type: string superseded_at: description: When a newer verification replaced this one. format: date-time title: Superseded At type: string expires_at: description: When this verification would have expired. format: date-time title: Expires At type: string required: - verified_at - superseded_at - expires_at title: IdentityVerificationHistoryItemResponse (v1) type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError v1.BusinessOperatorLinkStatus: description: |- 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. enum: - VERIFIED - UNDER_REVIEW - REJECTED title: BusinessOperatorLinkStatus type: string v1.ResumableWorkflowState: description: |- Lifecycle state of an asynchronous verification workflow, such as an identity submission: PENDING, EXECUTING, or WAITING while in flight, then a terminal COMPLETED, FAILED, EXPIRED, or CANCELLED. enum: - PENDING - EXECUTING - WAITING - COMPLETED - FAILED - EXPIRED - CANCELLED title: ResumableWorkflowState type: string v1.OnboardingVerdict: description: Normalized onboarding verdict used across provider-specific outputs. enum: - APPROVED - UNDER_REVIEW - REJECTED title: OnboardingVerdict type: string v1.IdentitySubmissionTerminalReasonResponse: description: Typed explanation for a submission that did not complete. properties: state: description: Terminal workflow state. enum: - FAILED - CANCELLED title: State type: string message: anyOf: - type: string - type: 'null' default: null description: Human-readable detail recorded by the workflow. title: Message required: - state title: IdentitySubmissionTerminalReasonResponse (v1) type: object securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````