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

**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}
  {
    "sub": "otV9EMJr-iG-dj-AHhrCslfdRkUUBQJ1",
    "hopae_loa": 3,
    "user": {
      "name": "OK TESTNUMBER",
      "given_name": "OK",
      "family_name": "TESTNUMBER",
      "birthdate": "1905-04-04"
    },
    "missing_claims": ["email", "phone_number"]
  }
  ```
</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`. Claims listed there weren’t provided by the source — handle fallbacks accordingly.
</Note>

### Match Flows Use the Same Names

The normalization catalog above also applies to match-capable providers: `matchData` 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. Hopae translates to the upstream IDP'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 [Create Verification — matchData](/api-reference/verifications/create-verification#param-match-data).

## Next Steps

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

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

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


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