> ## 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 an individual by pairwise reference

> Returns when your latest record of the individual was accepted, the keys it holds with their `basis` (`verified` or `attested`), and how many credentials, submissions, verifications and operator links they have, for an `individual_ref` issued to your organization. Any reference you hold for the person resolves, and the response carries the one your lists show for them. References issued to other organizations and unknown references are indistinguishable `404`s.



## OpenAPI

````yaml /api-reference/openapi.json get /issuance/identities/individuals/{individual_ref}
openapi: 3.1.0
info:
  title: baselayer-api-service
  version: 0.1.0
servers:
  - url: https://api.baselayer.com/
security: []
paths:
  /issuance/identities/individuals/{individual_ref}:
    get:
      tags:
        - Identities
      summary: Look up an individual by pairwise reference
      description: >-
        Returns when your latest record of the individual was accepted, the keys
        it holds with their `basis` (`verified` or `attested`), and how many
        credentials, submissions, verifications and operator links they have,
        for an `individual_ref` issued to your organization. Any reference you
        hold for the person resolves, and the response carries the one your
        lists show for them. References issued to other organizations and
        unknown references are indistinguishable `404`s.
      operationId: issuance_identities_individuals_get
      parameters:
        - name: individual_ref
          in: path
          required: true
          schema:
            title: Individual Ref
            type: string
      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 individual_ref is unknown or was issued to another organization
            — the two are indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                title: ResourceNotFound
                description: Could not locate the resource for the given URI.
                examples:
                  - type: resource_not_found
                    code: 1
                    message: Could not locate the resource for the given URI.
                    metadata: {}
        '422':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                title: ValidationFailed
                description: The request is invalid.
                examples:
                  - type: validation_failed
                    code: 7112
                    message: The request is invalid.
                    metadata: {}
      security:
        - APIKeyHeader: []
components:
  schemas:
    v1.IdentityStatusResponse:
      description: |-
        Body for ``GET /issuance/identities/individuals/{individual_ref}``.

        Strictly scoped to the calling organization: only links it covered with
        its own sessions are counted, 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:
        individual_ref:
          description: The queried pairwise individual reference.
          title: Individual Ref
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            The name on your organization's latest accepted record of the
            individual — the same value the list row carries. Null when your
            organization holds no accepted record of the individual. Mask it in
            shared surfaces; the API returns what the organization itself
            submitted.
          title: Display Name
        reference_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Your `reference_id` for the individual, on the reference they are
            listed under; null when you never sent one. A push or a `PATCH`
            answers the `reference_id` it wrote under.
          title: Reference Id
        created_at:
          description: When your organization first held a reference to the individual.
          format: date-time
          title: Created At
          type: string
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          default: null
          description: >-
            When your organization's latest record of the individual was
            accepted: a verification or a push. Null when it holds none.
          title: Updated At
        active_keys:
          $ref: '#/components/schemas/v1.RecordedActiveKeys'
          description: >-
            Each individual verification check the identity currently holds
            (e.g. `phone_possession`, `ssn_identity_match`), from the
            token-exchange profile's key vocabulary, with its `basis`
            (`verified` when Baselayer ran the check, `attested` when a customer
            vouched for it) and `time` (the UTC day, a NumericDate). A key an
            earlier verification proved stays held while the latest one carries
            the same values (the same phone for `phone_possession`).
        available_disclosure_paths:
          description: >-
            The subject-relative credential disclosure paths a mint from the
            current verification can disclose: a held key proves each and a
            value is on file, hash leaves included (e.g. `hashes.ssn`). Paths
            only, never values. Empty when this organization holds no current
            verification.
          items:
            type: string
          title: Available Disclosure Paths
          type: array
        operator_link_count:
          description: >-
            Businesses your organization holds an operator link to the
            individual for, in any status: the rows `GET
            /issuance/identities/operator_links?individual_ref=…` lists.
          title: Operator Link Count
          type: integer
        submission_count:
          description: >-
            This organization's approved verifications of the individual: the
            rows of `GET
            /issuance/identities/individuals/{individual_ref}/submissions`.
          title: Submission Count
          type: integer
        credential_counts:
          $ref: '#/components/schemas/v1.CredentialSummaryResponse'
          description: >-
            This organization's agent credentials for the individual, counting
            business credentials they acted for; the rows are `GET
            /issuance/credentials?individual_ref=…`.
        record_count:
          description: >-
            This organization's accepted records of the individual, the current
            one included: the rows of `GET
            /issuance/identities/individuals/{individual_ref}/records`.
          title: Record Count
          type: integer
      required:
        - individual_ref
        - created_at
        - operator_link_count
        - submission_count
        - credential_counts
        - record_count
      title: IdentityStatusResponse (v1)
      type: object
    Error:
      properties:
        type:
          type: string
          title: Type
          description: >-
            Stable snake_case name of the error. Branch on this, never on
            `message`.
        code:
          type: integer
          title: Code
          description: Integer catalog code of the error.
        message:
          type: string
          title: Message
          description: For a person reading a log; not stable and not localized.
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Context documented per `type`.
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: The `X-Request-ID` of the failed request.
      type: object
      required:
        - type
        - code
        - message
      title: Error
      description: The one body of every error a KYA route answers.
    v1.RecordedActiveKeys:
      additionalProperties:
        $ref: '#/components/schemas/v1.KeyEvidence'
      description: >-
        A credential's keys as signed, on its record and in API answers: the

        record's credential type names the vocabulary, so the names stay
        strings.

        Read-only, like the model.
      maxProperties: 9
      title: RecordedActiveKeys
      type: object
    v1.CredentialSummaryResponse:
      description: |-
        This organization's agent credentials for a business, or for a person
        counting the business credentials they acted for, counted.
      properties:
        issued_30d:
          description: Agent credentials issued in the last 30 days.
          title: Issued 30D
          type: integer
        active:
          description: Agent credentials neither revoked nor expired.
          title: Active
          type: integer
        revoked_30d:
          description: Agent credentials revoked in the last 30 days.
          title: Revoked 30D
          type: integer
      required:
        - issued_30d
        - active
        - revoked_30d
      title: CredentialSummaryResponse (v1)
      type: object
    v1.KeyEvidence:
      additionalProperties: false
      description: >-
        One key's basis and the UTC day it was established.


        Direct construction, ``KeyEvidence(...)``, raises ``TypeError``. Build

        evidence through the named constructors ``from_proof``, ``from_record``

        and ``proven_at``. ``model_validate`` is for parsing stored JSON that
        one

        of them serialized, never for building new evidence. The day is ours,

        never a customer's own timestamp, so sites cannot correlate on a value a

        customer chose.
      properties:
        basis:
          $ref: '#/components/schemas/v1.KeyBasis'
        time:
          title: Time
          type: integer
      required:
        - basis
        - time
      title: KeyEvidence
      type: object
    v1.KeyBasis:
      description: >-
        Who established a key: Baselayer ran the check, or a customer vouched
        for it.
      enum:
        - verified
        - attested
      title: KeyBasis
      type: string
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.