> ## 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. # List the people your organization has verified > Lists every person your organization holds a `prn_` reference for, newest verification first: their current verification state, what it can attest to, how many businesses they operate under your coverage, and how much credential activity they have seen. Filter by verification state, operator-link status and verification date; search by reference, name, email or phone. Scoped to your own population — references issued by other organizations are not listed and are not searchable. ## OpenAPI ````yaml /api-reference/openapi.json get /identities/principals openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /identities/principals: get: tags: - Identities summary: List the people your organization has verified description: >- Lists every person your organization holds a `prn_` reference for, newest verification first: their current verification state, what it can attest to, how many businesses they operate under your coverage, and how much credential activity they have seen. Filter by verification state, operator-link status and verification date; search by reference, name, email or phone. Scoped to your own population — references issued by other organizations are not listed and are not searchable. operationId: list_principals parameters: - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: >- Maximum number of records to return in a single page. Must be between 1 and 1000. default: 10 title: Limit description: >- Maximum number of records to return in a single page. Must be between 1 and 1000. - name: offset in: query required: false schema: anyOf: - type: integer minimum: 0 - type: 'null' description: >- Number of records to skip from the beginning. Use 0 for the first page. Cannot be used with cursor. title: Offset description: >- Number of records to skip from the beginning. Use 0 for the first page. Cannot be used with cursor. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Opaque pagination cursor token that identifies the position in the result set. Use the cursor from the previous response to get the next page. Cannot be used with offset. title: Cursor description: >- Opaque pagination cursor token that identifies the position in the result set. Use the cursor from the previous response to get the next page. Cannot be used with offset. - name: verification_state in: query required: false schema: anyOf: - $ref: '#/components/schemas/IdentityVerificationState' - type: 'null' description: >- Only identities in this derived state. SUPERSEDED never matches: the list carries one row per person — their current verification — and superseded snapshots are lineage, not population. title: Verification State description: >- Only identities in this derived state. SUPERSEDED never matches: the list carries one row per person — their current verification — and superseded snapshots are lineage, not population. - name: operator_link_status in: query required: false schema: anyOf: - $ref: '#/components/schemas/BusinessOperatorLinkStatus' - type: 'null' description: >- Only people holding at least one operator link in this status that your organization covered. title: Operator Link Status description: >- Only people holding at least one operator link in this status that your organization covered. - name: expires_before in: query required: false schema: anyOf: - format: date-time type: string - type: 'null' description: >- Only identities whose verification expires strictly before this instant — pass now + 30 days for the "expiring soon" needs-attention window. Already-expired identities match too; combine with `verification_state` to separate them. Must carry a UTC offset. title: Expires Before description: >- Only identities whose verification expires strictly before this instant — pass now + 30 days for the "expiring soon" needs-attention window. Already-expired identities match too; combine with `verification_state` to separate them. Must carry a UTC offset. - name: mint_failed_since in: query required: false schema: anyOf: - format: date-time type: string - type: 'null' description: >- Only identities your active application saw a typed credential mint refusal for at or after this instant. Must carry a UTC offset. title: Mint Failed Since description: >- Only identities your active application saw a typed credential mint refusal for at or after this instant. Must carry a UTC offset. - name: search in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: >- A `prn_` reference, or free text matched against name, email and phone. Every whitespace-separated term must match. title: Search description: >- A `prn_` reference, or free text matched against name, email and phone. Every whitespace-separated term must match. - name: start_date in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: 'Filter records created on or after this date (format: YYYY-MM-DD).' title: Start Date description: 'Filter records created on or after this date (format: YYYY-MM-DD).' - name: end_date in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- Filter records created on or before this date (format: YYYY-MM-DD). title: End Date description: 'Filter records created on or before this date (format: YYYY-MM-DD).' - name: tz in: query required: false schema: type: string description: >- IANA timezone identifier used to interpret start_date and end_date (defaults to UTC). examples: - UTC - America/Los_Angeles - Europe/London default: UTC title: Tz description: >- IANA timezone identifier used to interpret start_date and end_date (defaults to UTC). responses: '200': description: >- Paginated identities, newest verification first, scoped to the calling organization. content: application/json: schema: type: array items: $ref: '#/components/schemas/v1.IdentityListItemResponse' application/vnd.baselayer.v1+json: schema: type: array items: $ref: '#/components/schemas/v1.IdentityListItemResponse' headers: X-Total-Count: description: Total number of records matching the query. schema: type: integer X-Total-Pages: description: Total number of pages available based on the current limit. schema: type: integer X-Next-Cursor: description: >- Cursor for the next page (only present when using the keyset pagination and if `has_more` is true. schema: type: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: 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 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.IdentityListItemResponse: description: |- One person in ``GET /identities``. The row an operator scans a population by: who the identity is, whether it can still mint, and how much it has been used. Everything is scoped to the calling organization — the reference, the covered links counted, and the credentials counted are all its own. properties: principal_ref: description: This organization's pairwise reference to the person. title: Principal Ref type: string display_name: description: >- The verified name, as the latest snapshot recorded it. Mask it in shared surfaces; the API returns what the organization itself submitted. title: Display Name type: string verification_state: $ref: '#/components/schemas/v1.IdentityVerificationState' description: >- CURRENT, or EXPIRED (re-verify before minting). Derived from the snapshot's validity window, never stored. 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 active_keys: description: >- Dotted keys of the attributes the latest verification can attest to — the vocabulary credential disclosure uses. items: type: string title: Active Keys type: array linked_business_count: description: >- Businesses this organization covers a live operator link to for the person; rejected links are not counted. title: Linked Business Count type: integer credentials_minted_30d: description: >- Credentials this organization minted for the person in the last 30 days, counting business credentials it acted for. title: Credentials Minted 30D type: integer verified_at: description: When the latest verification was recorded. format: date-time title: Verified At type: string expires_at: description: When the latest verification expires. format: date-time title: Expires At type: string required: - principal_ref - display_name - verification_state - linked_business_count - credentials_minted_30d - verified_at - expires_at title: IdentityListItemResponse (v1) type: object 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 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 securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````