> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Verification UserInfo

> Return the verified claims for a completed verification, and on request the provenance and missing claims.

Returns the verified user data and, for `match` connections, the match outcome. The audit trail (`provenance`) and `missing_claims` are returned only when you request them with the query parameters below. Available when the session is `completed`, or when it failed with `error.code: "loa_insufficient"` (the lax assurance result).

## Headers

<ParamField header="Authorization" type="string" required>
  `Basic <base64(appId:appSecret)>`. See [Authentication](/v2/api-reference/authentication).
</ParamField>

## Path Parameters

<ParamField path="verificationId" type="string" required>
  The session id.
</ParamField>

## Query Parameters

<ParamField query="provenance" type="boolean" default="false">
  `true` (or `1`) adds the `provenance` block, including the connection identity under `provenance._metadata`. Omitted or any other value leaves it out.
</ParamField>

<ParamField query="missing_claims" type="boolean" default="false">
  `true` (or `1`) adds the `missing_claims` list. Omitted or any other value leaves it out.
</ParamField>

## Response

Connection identity appears only under `provenance._metadata`, never as top-level userinfo fields, so request `provenance=true` to read it. The IDs are snapshotted when the session is created.

<ResponseField name="sub" type="string" required>Subject identifier. In Hopae Connect this is the `verificationId`. A verification is a one-time event, not an account. Use `user.source_id` to recognise a returning person.</ResponseField>
<ResponseField name="hopae_loa" type="number">Numeric [Level of Assurance](/v2/guides/verifications/assurance), 1 to 5.</ResponseField>
<ResponseField name="hopae_loa_label" type="string">Human-readable assurance label (e.g. `substantial`).</ResponseField>
<ResponseField name="acr" type="string">Authentication Context Class Reference. Present when the provider asserted a LoA explicitly.</ResponseField>
<ResponseField name="provenance._metadata.provider_id" type="string">With `provenance=true`. The provider of the connection that ran, as a catalog provider id (e.g. `smart-id`, `google-wallet`).</ResponseField>
<ResponseField name="provenance._metadata.connection_id" type="string">The catalog connection id (e.g. `google-wallet-us-mdl`). Human-readable but opaque: read `provider_id` and `credential_id` instead of parsing it.</ResponseField>
<ResponseField name="provenance._metadata.credential_id" type="string">The credential that was verified (e.g. `us-mdl`).</ResponseField>
<ResponseField name="provenance._metadata.connection_instance_id" type="string">With `provenance=true`. The activated connection instance the session ran on (`conn_…`), the instance resolved at creation.</ResponseField>
<ResponseField name="verification_model" type="string" required>`disclosure` (attributes under `user`) or `match` (comparison under `match`, with `user` echoing the verified subset of what you submitted). See [Verification Model](/v2/guides/concepts/verification-model).</ResponseField>
<ResponseField name="missing_claims" type="string[]">Returned only with `missing_claims=true`. Requested claims the source could not provide. Includes `source_id` when it was requested but could not be derived for this person. `[]` when nothing is missing.</ResponseField>

<ResponseField name="user" type="object | null">
  The verified attributes, limited to the claims the workflow requested. For `match` connections it contains the verified subset of the values you submitted in `userInput`. Per-field providers: only fields with `matched: true`. Aggregate providers: every submitted field when the aggregate outcome is `true`, otherwise empty.

  <Expandable title="Common fields">
    <ResponseField name="name" type="string">Full name</ResponseField>
    <ResponseField name="given_name" type="string">Given name</ResponseField>
    <ResponseField name="family_name" type="string">Family name</ResponseField>
    <ResponseField name="middle_name" type="string">Middle name(s)</ResponseField>
    <ResponseField name="birthdate" type="string">`YYYY-MM-DD`</ResponseField>
    <ResponseField name="gender" type="string">Gender value</ResponseField>
    <ResponseField name="nationality" type="string">ISO 3166-1 alpha-2</ResponseField>
    <ResponseField name="email" type="string">Email address</ResponseField>
    <ResponseField name="email_verified" type="boolean">Whether the email is verified</ResponseField>
    <ResponseField name="phone_number" type="string">E.164 phone number</ResponseField>
    <ResponseField name="phone_number_verified" type="boolean">Whether the phone number is verified</ResponseField>
    <ResponseField name="address" type="object | string">Structured address</ResponseField>
    <ResponseField name="picture" type="string">Base64-encoded portrait</ResponseField>
    <ResponseField name="locale" type="string">BCP 47 locale</ResponseField>
    <ResponseField name="source_id" type="string">Stable identifier for the same person on this connection. Present only when `source_id` is selected in the workflow's data request and the connection can derive it.</ResponseField>
  </Expandable>

  See [Normalized User Data](/v2/guides/verifications/normalized-user-data) for the full catalog. Provider-specific claims may also appear.
</ResponseField>

<ResponseField name="match" type="object">
  Present only when `verification_model` is `match`.

  <Expandable title="Match fields">
    <ResponseField name="match.matched" type="boolean">Aggregate outcome, `true` only when every submitted field matched.</ResponseField>
    <ResponseField name="match.granularity" type="string">`per_field` or `aggregate`.</ResponseField>
    <ResponseField name="match.submitted_fields" type="string[]">The `userInput` keys that were compared.</ResponseField>
    <ResponseField name="match.details" type="object">Per-field outcomes keyed by field name (`per_field` only): `matched`, `submitted_value`, and optionally `similarity` (0 to 100).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="provenance" type="object">
  Returned only with `provenance=true`. What the source returned, as handed over by the provider. See [Return Data Model](/v2/guides/verifications/return-data-model).

  <Expandable title="Presentation">
    <ResponseField name="provenance.presentation.credentials[]" type="array">One entry per upstream credential presented for this verification.</ResponseField>
    <ResponseField name="provenance.presentation.credentials[].claims" type="object">The provider's raw response for this credential, in the provider's own field names. Returned for every verification model, match included.</ResponseField>
    <ResponseField name="provenance.presentation.credentials[].evidence" type="object">Signed proof material relayed from the source, when the provider issues it. See [Evidence & Data Integrity](/v2/guides/verifications/evidence).</ResponseField>
  </Expandable>

  <Expandable title="Metadata">
    <ResponseField name="provenance._metadata.verification_id" type="string">The session id.</ResponseField>
    <ResponseField name="provenance._metadata.verified_at" type="string">ISO 8601 completion time.</ResponseField>
    <ResponseField name="provenance._metadata.status" type="string">Session status at read time.</ResponseField>
    <ResponseField name="provenance._metadata.error" type="object">Present when the session ended with `loa_insufficient`.</ResponseField>
  </Expandable>

  Catalog identity is carried by `provenance._metadata.provider_id`, `connection_id`, `credential_id`, and `connection_instance_id`. It is never repeated at the top level of userinfo.
</ResponseField>

<ResponseField name="error" type="object">
  Present only for the one non-completed state this endpoint serves: a session that `failed` with `code: "loa_insufficient"` (the provider returned a lower LoA than the workflow asked for). The data is still returned so you can decide how to handle it.
</ResponseField>

<Note>
  Workflow decision nodes (`check-min-loa`, `check-claim`, `evaluate`) add their outputs to this response, for example `metLoa`, `hasClaim`, or `computed.<field>`. See [Workflow Nodes](/v2/guides/reference/workflow-nodes).
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.hopae.com/connect/v2/verifications/{verificationId}/userinfo?provenance=true&missing_claims=true' \
    --user '{appId}:{appSecret}'
  ```
</RequestExample>

<ResponseExample>
  ```json Disclosure (provenance=true&missing_claims=true) theme={null}
  {
    "user": {
      "given_name": "OK",
      "family_name": "TESTNUMBER",
      "name": "OK TESTNUMBER",
      "birthdate": "1905-04-04",
      "nationality": "LT",
      "source_id": "PNOLT-40504040001"
    },
    "missing_claims": [
      "email"
    ],
    "acr": "urn:hopae:loa:4",
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "verification_model": "disclosure",
    "provenance": {
      "presentation": {
        "credentials": [
          {
            "claims": {
              "documentNumber": "PNOLT-40504040001-MOCK-Q",
              "birthdate": "1905-04-04",
              "countryCode": "LT",
              "givenName": "OK",
              "surname": "TESTNUMBER"
            },
            "evidence": {
              "token": {
                "id_token": "<BASE64_ID_TOKEN>",
                "expires_at": "2026-09-03T10:19:52.000Z",
                "access_token": "<OPAQUE_ACCESS_TOKEN>",
                "token_type": "Bearer"
              },
              "names": "id_token;expires_at;access_token;token_type"
            }
          }
        ]
      },
      "_metadata": {
        "verification_id": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
        "verified_at": "2026-09-03T09:19:52.110Z",
        "status": "completed",
        "provider_id": "smart-id",
        "connection_id": "smart-id",
        "credential_id": "smart-id",
        "connection_instance_id": "conn_01J8XK2P4M9QR3TV"
      }
    },
    "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8"
  }
  ```

  ```json Match (provenance=true&missing_claims=true) theme={null}
  {
    "user": {
      "name": "Manuela Elisa da Mota",
      "cpf": "12345678900"
    },
    "missing_claims": [],
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "verification_model": "match",
    "match": {
      "matched": false,
      "granularity": "per_field",
      "submitted_fields": [
        "name",
        "birthdate",
        "cpf"
      ],
      "details": {
        "name": {
          "matched": true,
          "submitted_value": "Manuela Elisa da Mota",
          "similarity": 100
        },
        "birthdate": {
          "matched": false,
          "submitted_value": "1975-06-05"
        },
        "cpf": {
          "matched": true,
          "submitted_value": "12345678900"
        }
      }
    },
    "provenance": {
      "presentation": {
        "credentials": [
          {
            "claims": {
              "rfb_existe": true,
              "cnh_existe": true,
              "qrcode": {
                "nome": true,
                "data_nascimento": false
              }
            },
            "evidence": {
              "token": {
                "integrator_jws": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
                "token_type": "integrator"
              },
              "names": "integrator_jws;token_type"
            }
          }
        ]
      },
      "_metadata": {
        "verification_id": "019bc4f7-2b44-7f1a-9c3d-8e5b0a6f2c77",
        "verified_at": "2026-09-03T10:02:19.551Z",
        "status": "completed",
        "provider_id": "br-cpf",
        "connection_id": "br-cpf-cnh-match",
        "credential_id": "br-cnh-match",
        "connection_instance_id": "conn_01J8XK7T1B5NM0WD"
      }
    },
    "sub": "019bc4f7-2b44-7f1a-9c3d-8e5b0a6f2c77"
  }
  ```

  ```json Disclosure (no query parameters) theme={null}
  {
    "user": {
      "given_name": "OK",
      "family_name": "TESTNUMBER",
      "name": "OK TESTNUMBER",
      "birthdate": "1905-04-04",
      "nationality": "LT",
      "source_id": "PNOLT-40504040001"
    },
    "acr": "urn:hopae:loa:4",
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "verification_model": "disclosure",
    "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8"
  }
  ```
</ResponseExample>

<Note>
  `provenance.presentation.credentials[].claims` is the provider's own response in its native field names (for match providers, typically per-field confirmations). `userInput`, `match.submitted_fields`, and `match.details` use OIDC-normalized keys (e.g. `name`, `birthdate`), so the audit trail stays aligned with the source while your request and the outcome stay normalized.
</Note>

## Errors

| HTTP | Code | When |
| :- | :- | :- |
| 404 | `SESSION_VERIFICATION_NOT_FOUND` | Unknown id, a session of another app, or an environment mismatch |
| 409 | `SESSION_INVALID_STATUS_TRANSITION` | The session is not `completed` and is not a `failed` session with `error.code: "loa_insufficient"` |
| 403 | `AUTH_DATA_PROTECTED` | The session was started over OIDC with `private_mode` |


## OpenAPI

````yaml GET /verifications/{verificationId}/userinfo
openapi: 3.1.0
info:
  title: Hopae Connect Verification API
  version: 2.0.0
servers:
  - url: https://api.hopae.com/connect/v2
    description: Hopae Connect
security:
  - basicAuth: []
tags:
  - name: Verifications
paths:
  /verifications/{verificationId}/userinfo:
    get:
      tags:
        - Verifications
      summary: Get Verification UserInfo
      operationId: getVerificationUserInfo
      parameters:
        - name: verificationId
          in: path
          required: true
          description: The session id.
          schema:
            type: string
        - name: provenance
          in: query
          required: false
          description: >-
            `true` (or `1`) adds the `provenance` block, including the
            connection identity under `provenance._metadata`. Off by default.
          schema:
            type: boolean
            default: false
        - name: missing_claims
          in: query
          required: false
          description: '`true` (or `1`) adds the `missing_claims` list. Off by default.'
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Verified data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '403':
          description: >-
            `AUTH_DATA_PROTECTED`: user data cannot be released for this
            session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: AUTH_DATA_PROTECTED
                  message: Data protected
                  details: {}
                request_id: req_01J8XQ3V9K2M7N4P
        '404':
          description: >-
            `SESSION_VERIFICATION_NOT_FOUND`: unknown id, or created on another
            mode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SESSION_VERIFICATION_NOT_FOUND
                  message: Verification not found
                  details: {}
                request_id: req_01J8XQ3V9K2M7N4P
        '409':
          description: '`SESSION_INVALID_STATUS_TRANSITION`: the session is not `completed`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SESSION_INVALID_STATUS_TRANSITION
                  message: Not completed
                  details: {}
                request_id: req_01J8XQ3V9K2M7N4P
components:
  schemas:
    UserInfo:
      type: object
      properties:
        user:
          type: object
          description: >-
            Verified attributes, limited to the claims the workflow requested.
            `source_id` appears only when selected in the workflow and the
            source provided it. See [Normalized User
            Data](/v2/guides/verifications/normalized-user-data).
          additionalProperties: true
        missing_claims:
          type: array
          items:
            type: string
          description: >-
            Returned only with `missing_claims=true`. Requested claims the
            source could not provide (may include `source_id`).
        acr:
          type: string
          description: Authentication Context Class Reference.
        hopae_loa:
          type: number
          description: Numeric Level of Assurance, 1 to 5.
        hopae_loa_label:
          type: string
          description: LoA label.
        verification_model:
          type: string
          description: '`disclosure` or `match`.'
          enum:
            - disclosure
            - match
        match:
          type: object
          description: >-
            Match outcome: `matched`, `granularity`, `submitted_fields`,
            `details`. Match connections only.
        error:
          type: object
          description: >-
            Present when the achieved LoA was lower than requested
            (`loa_insufficient`).
        provenance:
          type: object
          description: >-
            Returned only with `provenance=true`. What the source returned, plus
            verification metadata. See [Return Data
            Model](/v2/guides/verifications/return-data-model).
          properties:
            presentation:
              type: object
              description: >-
                `credentials[]`, one entry per credential the source presented,
                each with the source's own `claims` as received and, when
                issued, `evidence`.
            _metadata:
              type: object
              description: >-
                Metadata about the verification and the connection that ran.
                These ids are not repeated at the top level.
              properties:
                verification_id:
                  type: string
                  description: The verification id. Same value as `sub`.
                verified_at:
                  type: string
                  format: date-time
                  description: When the verification completed.
                status:
                  type: string
                  description: Verification status when the result was read.
                error:
                  type: object
                  description: >-
                    Only when the verification ended with an error (for example
                    `loa_insufficient`).
                provider_id:
                  type: string
                  description: >-
                    Catalog provider id of the connection that ran (for example
                    `smart-id`).
                connection_id:
                  type: string
                  description: >-
                    Catalog connection id. Human-readable but opaque: read
                    `provider_id` and `credential_id` instead of parsing it.
                credential_id:
                  type: string
                  description: Catalog credential id of the connection that ran.
                connection_instance_id:
                  type: string
                  description: >-
                    Your app's activated instance of the connection, the id the
                    verification was started with (`conn_…`).
        sub:
          type: string
          description: >-
            The verification id. New for every verification, so it is not a
            stable user identifier. Use `user.source_id` to recognise a
            returning person. Always the last key.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
        request_id:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        `Basic base64(appId:appSecret)`. See
        [Authentication](/v2/api-reference/authentication).

````

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