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

# Normalized User Data

> Flat, standard OIDC claims (plus LoA metadata) you can rely on across providers

## Overview

Hopae Connect solves the fragmentation problem of identity providers by standardizing user attributes across all eID providers. No matter which provider your users choose, you receive consistent, predictable data formats.

### **The Problem: Data Chaos**

Each identity provider uses different attribute names for the same user information, creating significant integration complexity:

**Example: Attribute Naming Chaos**

| Information | Provider A | Provider B | Provider C |
| - | - | - | - |
| First Name | `firstName` | `given_name` | `firstname` |
| Last Name | `lastName` | `family_name` | `surname` |
| Birth Date | `dateOfBirth` | `birthdate` | `dob` |
| National ID | `personalNumber` | `ssn` | `nationalNumber` |

Without standardization, you would need to:

* Write custom mapping logic for each provider
* Maintain provider-specific code branches
* Handle different date formats and data types
* Update your code when providers change their schemas

### Normalized Attributes

Hopae Connect maps all provider variations into a attribute set based on [OpenID Connect Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

These are standard OpenID Connect claims representing the user's identity.

| Attributes | Type | Required | Notes/Example |
| - | - | - | - |
| `name` | string | No | Full name |
| `given_name` | string | No | |
| `family_name` | string | No | |
| `middle_name` | string | No | |
| `nickname` | string | No | |
| `preferred_username` | string | No | |
| `profile` | string | No | URL |
| `picture` | string | No | Base64-encoded image data |
| `gender` | string | No | `female`, `male`, `other` |
| `birthdate` | string | No | `YYYY-MM-DD` |
| `locale` | string | No | BCP 47 (`en-US`) |
| `email` | string | No | `user@example.com` |
| `email_verified` | boolean | No | true/false |
| `phone_number` | string | No | E.164 (`+1415555…`) |
| `phone_number_verified` | boolean | No | true/false |
| `address` | object | No | See Address structure below |
| `nationality` | string | No | ISO 3166-1 alpha-2 |

#### Address Claim Structure

| Attributes | Type | Notes/Format |
| - | - | - |
| `street_address` | string | Street/house/PO Box |
| `locality` | string | City |
| `region` | string | State/Province/Region |
| `postal_code` | string | ZIP/Postal code |
| `country` | string | ISO 3166-1 alpha-2 |

<Info>
  Personal attributes are returned under `/userinfo.user.*`. The ID Token contains no PII. It carries only technical claims (for example: `sub`, `acr`, `hopae_loa`).
</Info>

### Choosing which claims to request

You choose claims in the [workflow](/v2/guides/verifications/workflows), not per request: its **Claims** tab selects the claims for every connection, plus claims that only a particular connection can return. [Get Connections](/v2/api-reference/verifications/get-connections) shows each connection's `availableClaims` so you know what can be requested.

One claim is special: **`source_id`**, the identifier the source uses for this person, stable for the same person on the same connection. It is opt-in (tick **Source ID** on the workflow's **Claims** tab), not every connection provides one, and even a connection that does may not for a given verification, depending on the identity provider and the user's status with it. When it cannot be derived it is listed in `missing_claims`, and its value can change for the same person when the source claim behind it changes (for example a reissued document). See [Source ID](/v2/guides/verifications/return-data-model#which-claims-you-receive).

**Examples**: Provider data vs. normalized `/userinfo.user`:

<CodeGroup>
  ```json Provider Response (BankID Sweden) theme={null}
  {
    "personalNumber": "198507124567",
    "givenName": "Anders",
    "surname": "Eriksson",
    "name": "Anders Eriksson"
  }
  ```

  ```json UserInfo (user.*) theme={null}
  {
    "user": {
      "name": "OK TESTNUMBER",
      "given_name": "OK",
      "family_name": "TESTNUMBER",
      "birthdate": "1905-04-04"
    },
    "missing_claims": ["email", "phone_number"],
    "hopae_loa": 3,
    "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8"
  }
  ```
</CodeGroup>

### Data Availability

Not all attributes are available from all providers. The availability depends on each provider's capabilities and user consent.

<Note>
  If a claim is absent, check `missing_claims` in `/userinfo` (request it with `missing_claims=true`). Claims listed there weren’t provided by the source, so handle fallbacks accordingly.
</Note>

### Match Flows Use the Same Names

The normalization catalog above also applies to match connections: `userInput` keys are submitted using the normalized names (e.g. `name`, `birthdate`), and the result echoes them back unchanged in `match.submitted_fields` and as `match.details` keys. Fields with no normalized catalog entry (e.g. a provider-specific national ID lookup key) keep their provider-native name, as listed in the connection's `userInputSchema`. Hopae translates to the upstream source's native names at the provider boundary, so the `provenance` audit trail stays aligned with the source (e.g. `fullName`) while everything you submit and read back is normalized. See [User Input](/v2/api-reference/verifications/user-input).

## Next Steps

<CardGroup cols={2}>
  <Card title="OIDC Integration" icon="id-card" href="/v2/guides/oidc-integration">
    Implement standardized attributes
  </Card>

  <Card title="OIDC UserInfo" icon="id-card" href="/v2/api-reference/oidc/userinfo">
    Retrieve detailed context and evidence
  </Card>

  <Card title="Verification Process" icon="flow-chart" href="/v2/guides/verifications/verification-flow">
    Understanding the flow
  </Card>
</CardGroup>


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