# Contract Examples

## ensure-by-email

Request:

```json
{
  "email": "pilot@example.com",
  "registration_context": {
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad"
  }
}
```

Created response:

```json
{
  "outcome": "created",
  "user_id": "user-123"
}
```

Existing response:

```json
{
  "outcome": "existing",
  "user_id": "user-123"
}
```

Blocked response:

```json
{
  "outcome": "blocked",
  "block_reason_code": "policy_blocked"
}
```

## account aggregate

```json
{
  "account": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "user_name": "player-abcdefgh",
    "display_name": "PilotNova",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "declared_country": "DE",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:00:00Z"
  }
}
```

## update profile

Request:

```json
{
  "display_name": "NovaPrime"
}
```

Success:

```json
{
  "account": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "user_name": "player-abcdefgh",
    "display_name": "NovaPrime",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:05:00Z"
  }
}
```

Conflict:

```json
{
  "error": {
    "code": "conflict",
    "message": "request conflicts with current state"
  }
}
```

## update settings

Request:

```json
{
  "preferred_language": "fr-FR",
  "time_zone": "Europe/Paris"
}
```

## admin lookup by e-mail

Request:

```json
{
  "email": "pilot@example.com"
}
```

Success:

```json
{
  "user": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "user_name": "player-abcdefgh",
    "display_name": "PilotNova",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:00:00Z"
  }
}
```

## declared-country sync

Request:

```json
{
  "declared_country": "DE"
}
```

Response:

```json
{
  "user_id": "user-123",
  "declared_country": "DE",
  "updated_at": "2026-04-09T10:10:00Z"
}
```

## shared error envelope

```json
{
  "error": {
    "code": "invalid_request",
    "message": "request is invalid"
  }
}
```