> ## 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.

# Push an individual you verified

> Records an individual you verified yourself, named by your `reference_id`. Baselayer runs no check: each key you send in `attestations` reads `attested`, or `verified` where Baselayer verified the same values.

It answers `201` when the `reference_id` is new to your application, and `200` when you sent it before: the push then replaces your statement of the individual it names. A new `reference_id` can still name an individual you already hold; the `individual_ref` says which. Every push writes a new record, so `updated_at` moves; there is no `Idempotency-Key`. A `national_id` other than the one you hold for the individual, under any of your references, is refused with `409`.

The response carries the `individual_ref` your lists show for the individual, and the `reference_id` you sent.

Three ways to onboard an individual: a hosted enrollment (`POST /onboarding/sessions`), where the applicant verifies on Baselayer's page; a direct verification (`POST /issuance/identities/verifications`), where Baselayer checks an identity you collected; and a push (`POST /issuance/identities/individuals`), where you send an individual you verified yourself. On the last two your `reference_id` names one individual. A `reference_id` a hosted enrollment carried belongs to the first individual it was stamped on, so a later direct verification or push under it names that individual. Individuals only: a business is verified directly.



## OpenAPI

````yaml /api-reference/openapi.json post /issuance/identities/individuals
openapi: 3.1.0
info:
  title: baselayer-api-service
  version: 0.1.0
servers:
  - url: https://api.baselayer.com/
security: []
paths:
  /issuance/identities/individuals:
    post:
      tags:
        - Identities
      summary: Push an individual you verified
      description: >-
        Records an individual you verified yourself, named by your
        `reference_id`. Baselayer runs no check: each key you send in
        `attestations` reads `attested`, or `verified` where Baselayer verified
        the same values.


        It answers `201` when the `reference_id` is new to your application, and
        `200` when you sent it before: the push then replaces your statement of
        the individual it names. A new `reference_id` can still name an
        individual you already hold; the `individual_ref` says which. Every push
        writes a new record, so `updated_at` moves; there is no
        `Idempotency-Key`. A `national_id` other than the one you hold for the
        individual, under any of your references, is refused with `409`.


        The response carries the `individual_ref` your lists show for the
        individual, and the `reference_id` you sent.


        Three ways to onboard an individual: a hosted enrollment (`POST
        /onboarding/sessions`), where the applicant verifies on Baselayer's
        page; a direct verification (`POST /issuance/identities/verifications`),
        where Baselayer checks an identity you collected; and a push (`POST
        /issuance/identities/individuals`), where you send an individual you
        verified yourself. On the last two your `reference_id` names one
        individual. A `reference_id` a hosted enrollment carried belongs to the
        first individual it was stamped on, so a later direct verification or
        push under it names that individual. Individuals only: a business is
        verified directly.
      operationId: issuance_identities_individuals_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1.IndividualPushRequest'
          application/vnd.baselayer.v1+json:
            schema:
              $ref: '#/components/schemas/v1.IndividualPushRequest'
      responses:
        '200':
          description: >-
            You sent the `reference_id` before; the push replaced your statement
            of the individual.
          headers:
            Location:
              description: The individual.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1.IdentityStatusResponse'
            application/vnd.baselayer.v1+json:
              schema:
                $ref: '#/components/schemas/v1.IdentityStatusResponse'
        '201':
          description: The `reference_id` is new to your application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1.IdentityStatusResponse'
            application/vnd.baselayer.v1+json:
              schema:
                $ref: '#/components/schemas/v1.IdentityStatusResponse'
          headers:
            Location:
              description: The individual.
              schema:
                type: string
        '409':
          description: >-
            The individual holds a different `national_id`
            (`identity_national_id_changed`), or a concurrent change
            (`request_conflict`, with `Retry-After`): send the request again.
          headers:
            Retry-After:
              description: 'On `request_conflict`: seconds to wait.'
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The individual does not hold together.
          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: {}
        '502':
          description: >-
            The address service failed; nothing was written. Send the request
            again after `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before sending again.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                title: ThirdPartyServiceFailure
                description: >-
                  The request could not be completed due to a failure in an
                  external service.
                examples:
                  - type: third_party_service_failure
                    code: 7
                    message: >-
                      The request could not be completed due to a failure in an
                      external service.
                    metadata: {}
      security:
        - APIKeyHeader: []
components:
  schemas:
    v1.IndividualPushRequest:
      additionalProperties: false
      description: |-
        Pushes an individual you verified yourself, named by your
        ``reference_id``. A ``reference_id`` you have sent before replaces that
        individual's statement.
      properties:
        reference_id:
          description: Your id for this individual.
          maxLength: 128
          minLength: 1
          title: Reference Id
          type: string
        individual:
          $ref: '#/components/schemas/v1.PushedIndividualPayload'
          description: The individual, as you verified them.
      required:
        - reference_id
        - individual
      title: IndividualPushRequest (v1)
      type: object
    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.PushedIndividualPayload:
      additionalProperties: false
      description: |-
        An individual a customer verified itself: the whole statement, which
        replaces the one it sent before.
      properties:
        given_name:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: Legal given (first) name.
          title: Given Name
        middle_name:
          anyOf:
            - maxLength: 128
              type: string
            - type: 'null'
          default: null
          description: Legal middle name, if any.
          title: Middle Name
        family_name:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: Legal family (last) name.
          title: Family Name
        birthdate:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          default: null
          description: Date of birth (YYYY-MM-DD).
          title: Birthdate
        phone_number:
          anyOf:
            - pattern: ^\+[1-9]\d{1,14}$
              type: string
            - type: 'null'
          default: null
          description: Phone number in E.164 format.
          title: Phone Number
        email:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Email address.
          title: Email
        address:
          anyOf:
            - maxLength: 500
              minLength: 2
              type: string
            - type: 'null'
          default: null
          description: >-
            Residential address as a single line, normalized server-side. An
            address that cannot be matched to a deliverable address is not
            stored.
          examples:
            - 1640 Riverside Drive, Hill Valley, CA 95420
          title: Address
        national_id:
          anyOf:
            - $ref: '#/components/schemas/v1.NationalId'
            - type: 'null'
          default: null
          description: National id.
        attestations:
          anyOf:
            - items:
                $ref: '#/components/schemas/v1.AttestationRequest'
              maxItems: 5
              type: array
            - type: 'null'
          default: null
          description: >-
            The keys you verified for these values. Each replaces the
            attestations you sent before.
          title: Attestations
      title: PushedIndividualPayload (v1)
      type: object
    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.NationalId:
      additionalProperties: false
      description: A person's national id. Its country is in its ``type``.
      properties:
        type:
          $ref: '#/components/schemas/v1.NationalIdType'
          description: '`us_ssn`, the only type accepted today.'
        value:
          description: >-
            The id itself: a US SSN's nine digits; separators are accepted and
            stripped.
          examples:
            - 123-45-6789
          format: password
          title: Value
          type: string
          writeOnly: true
      required:
        - type
        - value
      title: NationalId (v1)
      type: object
    v1.AttestationRequest:
      additionalProperties: false
      description: |-
        A key you verified yourself and vouch for. It reads ``attested``,
        or ``verified`` where Baselayer verified the same values.
      properties:
        key:
          $ref: '#/components/schemas/v1.IndividualActiveKey'
          description: >-
            The key you verified: `phone_possession`, `email_possession`,
            `ssn_identity_match` or `dob_identity_match`. `watchlist_clear`
            cannot be attested.
      required:
        - key
      title: AttestationRequest (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.NationalIdType:
      description: |-
        A person's national identifier, its country in its name. Only the
        types a provider checks are members.
      enum:
        - us_ssn
      title: NationalIdType
      type: string
    v1.IndividualActiveKey:
      description: |-
        Attestation-primitive keys for an individual.

        Values are the KYA spec's wire form (lowercase snake_case); they appear
        verbatim in minted credentials and on identity records.
      enum:
        - phone_possession
        - email_possession
        - dob_identity_match
        - ssn_identity_match
        - watchlist_clear
      title: IndividualActiveKey
      type: string
    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.