# Prosperity Partner Integration — Complete Documentation

> This file contains the complete partner integration documentation for the Prosperity insurance platform.
> It is optimized for consumption by AI coding assistants and LLMs.
> Source: https://partner.life.li/integration-docs

---

## AI-Assisted Integration

URL: https://partner.life.li/integration-docs/ai-integration

# AI-Assisted Integration

Use the **Copy Prompt** buttons in our API guides to start an integration with an AI coding assistant. Each prompt provides the request, examples and API rules to work from.

Each prompt includes the actual GraphQL schema types (SDL) read directly from our source code, so the type definitions, field constraints, and documentation comments are always in sync with the API.

## Copy Prompts (Per Operation)

Each page in the [Platform Integration](https://partner.life.li/integration-docs/platform-integrations) section has focused, self-contained prompts you can copy directly into your AI coding assistant:

### API Setup
- [Platform GraphQL API](https://partner.life.li/integration-docs/platform-integrations/graphql-api) — prompt to set up the authenticated API client

### Creating Offers
- [Creating Offers](https://partner.life.li/integration-docs/platform-integrations/creating-offers) — per-product prompts for:
  - Liechtenstein Life Invest (Germany)
  - Liechtenstein Life Wealth (Germany)
  - Prosperity Plus Germany (Germany)
  - Prosperity 3A (Switzerland)
  - Existing customer offers

### Creating Pre-Registrations

- [Creating pre-registrations](https://partner.life.li/integration-docs/platform-integrations/pre-registrations) — an AVD Plus prompt for existing and new customers, including broker access, preparation emails, invitations and safe retry handling.
- The same guide explains how to register a customer through the API, then select them in Partner Life to prepare the AVD flow there.

### Other Operations
- Fetch offer and download PDF
- Update customer information
- Look up customer by email

Each prompt includes the exact GraphQL mutation/query, working example variables, authentication setup, relevant schema types (SDL), and product-specific notes. Just copy, paste, and tell your AI what to build.

## Schema Reference

Browse the full GraphQL schema for the Partner Platform API:

- [Schema Reference](https://partner.life.li/integration-docs/docs/schema) — browsable, auto-generated documentation for every type, input, enum, union, and interface
- [Platform Integration API Explorer](https://partner.life.li/integration-docs/platform-integrations/graphql-api) — interactive playground with full schema introspection

The schema reference is auto-generated from the source `.gql` files to stay in sync with the API.

## llms.txt (Auto-Discovered by AI Tools)

Our documentation follows the [llms.txt standard](https://llmstxt.org/). AI tools that support this standard will automatically discover and consume our documentation.

- **Index:** [/llms.txt](https://partner.life.li/integration-docs/llms.txt) — lightweight summary with links to all pages
- **Full content:** [/llms-full.txt](https://partner.life.li/integration-docs/llms-full.txt) — complete documentation in one AI-optimized file

## Interactive GraphQL Playground

Each API documentation page includes an embedded GraphQL playground where you can explore the schema, run queries, and test mutations directly:

- [Platform Integration API Explorer](https://partner.life.li/integration-docs/platform-integrations/graphql-api) — for customer registration, complete offers and AVD Plus pre-registrations
- [Digital Onboarding API Explorer](https://partner.life.li/integration-docs/customer-digital-onboarding/graphql-api) — for partial offers with customer onboarding

## Which API Do I Need?

| Use Case | API | Graph |
|----------|-----|-------|
| You have **all customer data** and want to create complete offers | Partner Platform | `partner-platform` |
| You want to prepare an **AVD Plus pre-registration** for an existing or new customer | Partner Platform | `partner-platform` |
| You want to **register a customer**, then prepare their AVD flow in Partner Life | Partner Platform | `partner-platform` |
| You have **partial data** and want customers to complete the offer in-app | Partner (Digital Onboarding) | `partner` |

## Need Help?

If you need assistance with AI-assisted integration or have questions, please reach out to our support team.

---

## BiPRO Integration

URL: https://partner.life.li/integration-docs/bipro

# BiPRO Integration

Receive policy documents and optional GDV portfolio exports from Liechtenstein Life in your broker management system using the **BiPRO Norm 430** SOAP interface. Shipments are available to fetch, process, and acknowledge.

## Credentials

Your **Client ID** and **Client Secret** are displayed in [Partner Life](https://partner.life.li/my/profile/bipro) under **Profile → BiPRO Integration**. The secret is shown once when the integration is created — store it securely. You can rotate it at any time from the same page.

**Note:**

### Optional GDV exports

GDV delivery is off by default for each connection. In Partner Life, open the connection's BiPRO settings, enable **Provide GDV portfolio data**, and confirm with your passkey. Creating credentials alone does not enable GDV.

The first export is prepared in the background, followed by weekly exports of authorised German-market contracts. Use `listShipments` and `getShipment` to retrieve completed exports, then download the ZIP from `<allg:Datenlink>` using your Bearer token. Requests do not trigger generation. Turning the setting off stops GDV generation and downloads.

## Environments

| Environment | Base URL |
|-------------|----------|
| Test (Stable) | `https://api.stable.life.li` |
| Production | `https://api.life.li` |

Use the test environment for all initial integration work. Production credentials are separate and must be obtained after test verification.

## Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/bipro/oauth/token` | `POST` | Exchange client credentials for a Bearer token |
| `/bipro/.well-known/jwks.json` | `GET` | Public JWKS for verifying issued tokens |
| `/bipro/norm410/2.7` | `POST` | BiPRO Norm 260/410 SOAP token service (WS-Trust) |
| `/bipro/norm410/2.7?wsdl` | `GET` | WSDL for the Norm 260/410 SOAP token service |
| `/bipro/norm430/2.7` | `POST` | BiPRO Norm 430 SOAP endpoint |

## Authentication

Authentication uses the **OAuth 2.0 client credentials** flow. Request a token before each SOAP session — tokens are valid for **15 minutes**.

### 1. Obtain a token

```bash
curl -X POST https://api.life.li/bipro/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=bipro:transfer"
```

Response:

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "bipro:transfer"
}
```

### 2. Call the SOAP endpoint

Pass the token in the `Authorization` header on every SOAP request:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

**Note:**
The token endpoint allows a maximum of **10 requests per 60 seconds** per Client ID. Re-use tokens until they are close to expiry rather than requesting a new one per SOAP call.

## BiPRO STS (Norm 260/410) — Username/Password

If your platform speaks WS-Trust rather than OAuth 2.0, request tokens through the BiPRO Norm 260/410 SecurityTokenService instead. Both paths issue the same underlying token and share one rate limit — use whichever fits your SOAP stack.

Use the same **Client ID** and **Client Secret** as the OAuth flow: Client ID as the WS-Security username, Client Secret as the password. Credentials are per broker — each broker platform stores each broker's own Client ID and Secret from [Partner Life](https://partner.life.li/my/profile/bipro), not a single shared account.

The WSDL is published at:

```
GET https://api.life.li/bipro/norm410/2.7?wsdl
```

### 1. Request a token

Send a WS-Trust `RequestSecurityToken` with a WS-Security `UsernameToken`:

```bash
curl -X POST https://api.life.li/bipro/norm410/2.7 \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>YOUR_CLIENT_ID</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">YOUR_CLIENT_SECRET</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </S:Header>
  <S:Body>
    <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
      <wst:TokenType>http://schemas.xmlsoap.org/ws/2005/02/sc/sct</wst:TokenType>
      <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</wst:RequestType>
    </wst:RequestSecurityToken>
  </S:Body>
</S:Envelope>'
```

`TokenType` and `RequestType` must match exactly as shown — any other value returns a SOAP fault.

### 2. Read the response

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <wst:RequestSecurityTokenResponse xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
      <wst:RequestedSecurityToken>
        <wsc:SecurityContextToken xmlns:wsc="http://schemas.xmlsoap.org/ws/2005/02/sc">
          <wsc:Identifier>bipro:eyJ...</wsc:Identifier>
        </wsc:SecurityContextToken>
      </wst:RequestedSecurityToken>
      <wst:Lifetime xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsu:Created>2026-07-06T12:00:00Z</wsu:Created>
        <wsu:Expires>2026-07-06T12:15:00Z</wsu:Expires>
      </wst:Lifetime>
    </wst:RequestSecurityTokenResponse>
  </soap:Body>
</soap:Envelope>
```

The `<wsc:Identifier>` is `bipro:`-prefixed and valid for **15 minutes**, matching `<wsu:Created>`/`<wsu:Expires>`. Store the full identifier, prefix included — you'll need it as-is for the SOAP header below.

### 3. Call Norm 430 with the token

Present the identifier as a `SecurityContextToken` in the SOAP header:

```xml
<soap:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsc:SecurityContextToken xmlns:wsc="http://schemas.xmlsoap.org/ws/2005/02/sc">
      <wsc:Identifier>bipro:eyJ...</wsc:Identifier>
    </wsc:SecurityContextToken>
  </wsse:Security>
</soap:Header>
```

The HTTP `Authorization: Bearer YOUR_ACCESS_TOKEN` header from the OAuth flow above still works too — the `bipro:` prefix is optional there, the server strips it automatically if present.

**Note:**
The Norm 260/410 token service shares its rate limit with `/bipro/oauth/token`: **10 requests per 60 seconds** per Client ID, counted across both endpoints combined. Re-use tokens until they are close to expiry.

### Faults

Errors come back as a SOAP fault with a `nachr:BiproException` detail carrying a `MeldungID`. Authentication failures — unknown Client ID, wrong secret, or a disabled integration — all return the same fault (`MeldungID 00960`), so a failed request never reveals which part of the credential pair was wrong. This fault shape is specific to this STS endpoint — Norm 430 authentication failures return the transfer service's own fault format.

## SOAP Operations

All operations are sent as `POST` requests to `/bipro/norm430/2.7` with `Content-Type: text/xml`.

### listShipments

Lists available (unacknowledged) shipments for your integration.

```bash
curl -X POST https://api.life.li/bipro/norm430/2.7 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tran="http://www.bipro.net/namespace/transfer"
  xmlns:nachr="http://www.bipro.net/namespace/nachrichten">
  <soap:Body>
    <tran:listShipments>
      <tran:Request>
        <nachr:BiPROVersion>2.7.0.1.0</nachr:BiPROVersion>
        <tran:BestaetigeLieferungen>false</tran:BestaetigeLieferungen>
      </tran:Request>
    </tran:listShipments>
  </soap:Body>
</soap:Envelope>'
```

The response contains a `<tran:Lieferung>` element for each available shipment, each with an `<tran:ID>` you use for `getShipment` and `acknowledgeShipment`.

### getShipment

Fetches the shipment payload, with inline content in `<allg:Daten>` or a download URL in `<allg:Datenlink>`. GDV exports use a download URL.

```bash
curl -X POST https://api.life.li/bipro/norm430/2.7 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tran="http://www.bipro.net/namespace/transfer"
  xmlns:nachr="http://www.bipro.net/namespace/nachrichten">
  <soap:Body>
    <tran:getShipment>
      <tran:Request>
        <nachr:BiPROVersion>2.7.0.1.0</nachr:BiPROVersion>
        <tran:ID>SHIPMENT_ID</tran:ID>
      </tran:Request>
    </tran:getShipment>
  </soap:Body>
</soap:Envelope>'
```

For inline document content, decode `<allg:Daten>` from the response:

```bash
# Extract and decode the base64 document from <allg:Daten>
echo "BASE64_CONTENT" | base64 -d > document.pdf
```

Key fields in the response:

| Field | Description |
|-------|-------------|
| `<allg:Daten>` | Base64-encoded document content |
| `<allg:Datenlink>` | Authenticated download URL; GDV exports are ZIP files |
| `<allg:Dateiname>` | Filename (e.g. `policy-12345.pdf`) |
| `<allg:Dateityp>` | File type |
| `<allg:Bezeichnung>` | Document label |

### acknowledgeShipment

Confirm receipt of a shipment. Call this after successfully processing the document. Acknowledged shipments no longer appear in `listShipments`.

```bash
curl -X POST https://api.life.li/bipro/norm430/2.7 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tran="http://www.bipro.net/namespace/transfer"
  xmlns:nachr="http://www.bipro.net/namespace/nachrichten">
  <soap:Body>
    <tran:acknowledgeShipment>
      <tran:Request>
        <nachr:BiPROVersion>2.7.0.1.0</nachr:BiPROVersion>
        <tran:ID>SHIPMENT_ID</tran:ID>
      </tran:Request>
    </tran:acknowledgeShipment>
  </soap:Body>
</soap:Envelope>'
```

A successful response includes `<StatusID>OK</StatusID>`.

## Recommended polling flow

1. `listShipments` — identify new shipment IDs
2. `getShipment` — download and process each document
3. `acknowledgeShipment` — confirm receipt

Repeat on a schedule (e.g. every few minutes). Only unacknowledged shipments appear in `listShipments`.

## Security best practices

- Store your Client Secret in a secrets manager — never in source code or config files
- Request tokens server-side only — never expose credentials to client-side code
- Rotate your Client Secret periodically from the [Partner Life portal](https://partner.life.li/my/profile/bipro)
- Use HTTPS for all requests (enforced — plain HTTP is rejected)

---

## Creating Offers With Onboarding Customer Flows

URL: https://partner.life.li/integration-docs/customer-digital-onboarding/creating-offers

# Creating Offers With Onboarding Customer Flows

## Prerequisites

- You have received your API Key (for stable and production environment)

## Integrating our product

There are two ways to integrate our product – both lead the user from your website into our policy application flow (themed as per your brand guidelines) seamlessly.

### Option 1: Embedding our user creation widget

![User Creation Widget](https://partner.life.li/integration-docs/img/user-creation-widget.webp)

You can integrate our user creation/registration widget inside your website as an `<iframe>` with the URL `https://example.com/partner/register`. On successful user creation, a verification email is then sent to the user with a verification link which will automatically redirect them to our policy application flow.

For a more customized experience, please have a look at our API. Use the register widget as a reference for implementing the consent checkboxes.

### Option 2: Integrating through our Partner API (bringing customers to our UI for verification and submission)

If you already have information about the user or have a custom onboarding experience, you can integrate our product using the Partner API to create the user with the relevant data points. A successful request will provide you with a magic link (if the user is already verified on your platform) that, when used, will automatically login into the user account and take them to our policy application flow with the additional data already being filled in for them.

```mermaid
sequenceDiagram
autonumber
participant Verified User
participant Your Software
participant Our Partner API
participant Our Website
Note right of Our Website: Custom themed
    Verified User -->>+ Your Software: Provides information
    Your Software -->>+ Our Partner API: trigger  createUser API
    Our Partner API -->>- Your Software: Response (with magic-link)
    Your Software -->>+ Our Website: redirect to magic-link (automatically login user)
```

#### Unverified user

The flow differs slightly in the case of a user who is not verified beforehand. On creating the unverified user on our platform, we will send the user a verification email with a verification link that will also work as a magic link.

```mermaid
sequenceDiagram
autonumber
participant Unverified User
participant Your Software
participant Our Partner API
participant Our Website
Note right of Our Website: Custom themed
    Unverified User -->>+ Your Software: Provides information
    Your Software -->>+ Our Partner API: trigger  createUser API
    Our Partner API -->>- Unverified User: E-mail verification (sent to the user)
    Unverified User -->>+ Our Website: Verification link (verifies and automatically login user)
```

### Option 3: API-only integration with Partner API (for partners with broker licenses)

If you already have all information about the user, you can integrate our product end-to-end with our Partner API and provide custom interfaces for the customers and brokers.

API-only integration allows you to create a flow from generating an offer for a customer to submitting the documents and applying for the offer with the insurance provider. This integration is for partners who want to create their broker dashboards to process and manage customers and complete another broker-related task without using external tools or interfaces for both brokers and customers.

The initial part of the flow remains the same as other integration. You can request the partner API to create a user with an offer. Once the user is created, you can use the user ID to perform additional actions on the offer.

```mermaid
sequenceDiagram
autonumber
participant Verified User
participant Your Software
participant Our Partner API
    Verified User -->>+ Your Software: Provides information
    Your Software -->>+ Our Partner API: trigger  createUser API
    Our Partner API -->>- Your Software: Response with UserID, OfferID, MagicLink
```

- If you created the user as a pre-verified user, you can upload the identity verification document.
- The next step is to generate a policy ID from the offer, which generates the application form, and validates the user and offer request, including checks on the combination of funds, investment risk level, and sustainability choices.
- The application is available for download once the policy ID is generated through the user query and uploaded back once the customer and the broker have signed it.
- The last step is to submit the offer to the insurance provider for verification and being issued, it can only be done once the signed application form has been uploaded.
- Once the offer has been submitted to the insurance company, no other mutation can be performed.
- The user query provides additional information about the verification status, signed application form upload status, and policy ID (if generated).

```mermaid
sequenceDiagram
autonumber
participant User
participant Brokers
participant Our Partner API
    Brokers -->>+ Our Partner API: Uploads ID Verification (mutation uploadIdentityVerificationDocument)
    Brokers -->>+ Our Partner API: Generate Policy ID (mutation validateAndGeneratePolicyID)
    Brokers -->>+ Our Partner API: Request application form (query user with policyApplicationForm field)
    Our Partner API -->>- Brokers: Use download link (PDF - valid for 5 mins)
    Brokers -->>+ User: Partner sends form to the user
    User -->- Brokers: Signed form received from the user
    Brokers -->>+ Our Partner API: Upload double-signed form (mutation uploadSignedApplicationForm)
    Brokers -->>+ Our Partner API: Submit to LLA (mutation submitOfferForIssuance)
```

**Note:**
This integration only works when the user/offer is created with all possible
inputs prefilled in the createUser mutation. If the information is missing or
invalid, we do not provide APIs to fix these issues, we return the response
from the insurance provider's API, and any problems with the offer have to be
fixed on the insurance provider's broker portal.

### Option 4: Post-pickup only integration

Partners can also have a limited integration of our application for users who have already picked up their policies without the onboarding experience. These users have an ongoing policy and have already opened their on the policy pickup email, created account on our application, and verified and picked up their policy.

This flow is for partners who have their own application and sell product outside of our application. This flow also supports all Liechtenstein Life insurance products.

Partners can fetch the details about their customers who are using our application through multiple ways:

- Use the GraphQL API to fetch all users using the `users` query
- You can subscribe to our webhook (by subscribing to `POLICY_ACTIVATED` event) this will notify the partners when new users are created that are associated with them.

Both these API steps result in user IDs that can be used to generate magic-links which can then be used to load the application with the user already logged in within an iframe.

```mermaid
sequenceDiagram
autonumber
participant Our Partner API
participant Partner System
participant Partner Website
    Our Partner API -->>+ Partner System: Fetch all users from GraphQL
    Our Partner API -->>+ Partner System: Recieved `POLICY_ACTIVATED` event webhook.
    Partner System -->>+ Our Partner API: Request magiclink for a certain user.
    Our Partner API -->>- Partner Website: Show the magiclink in an iframe.
```

## GraphQL API

- Detailed instructions on how to setup our graphQL API can be found in the [Our GraphQL API](https://partner.life.li/integration-docs/customer-digital-onboarding/graphql-api) section.
- The primary mutation you can start the integration process with is `createUser`. The operation can look like this:

```gql
mutation Mutation($user: UserInput!) {
  createUser(user: $user) {
    __typename
    ... on CreatedUnverifiedUser {
      id
    }
    ... on CreatedVerifiedUser {
      id
      magicLinkUrl
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

**The schema is fully commented, so consider the Playground as the API reference ("Docs" on the right).**

We are handling errors inside of our schema (see `ErrorInterface` above). Possible errors are self-documenting and you know what to handle ahead of time. ([More on the pattern](https://sachee.medium.com/200-ok-error-handling-in-graphql-7ec869aec9bc))

Never query the error types directly and always access errors through the `ErrorInterface` as laid out above. This way you can avoid breaking changes, caused through added or removed errors.

## Registering webhooks

We also support registering your own webhooks that are triggered when meaningful policy and user update events occur. You can read about webhooks in the API documentation within the `registerWebhook` mutation.

## Integrating into native apps

- Use the partner API to get a magic link for your logged-in user.
- Load the magic link in a web-view as a separate tab or a modal.
- Ensure that the cookies are persisted between sessions so that the magic link does not have to be regenerated when reopening the app.

---

## Partner GraphQL API

URL: https://partner.life.li/integration-docs/customer-digital-onboarding/graphql-api

# Partner GraphQL API

The Partner GraphQL API provides advanced capabilities for creating and managing complete offers. Access the API at:

- Test Environment: [https://api.stable.life.li/graphql/partner](https://api.stable.life.li/graphql/partner)
- Production: [https://api.life.li/graphql/partner](https://api.life.li/graphql/partner)

## Authentication

Both endpoints include a GraphQL playground for interactive API exploration. To authenticate:

1. In the browser authentication popup:

   - Leave the username empty
   - Enter your API key as the password

2. In the playground's Headers section, add:
   ```json
   {
     "Authorization": "Bearer YOUR-API-KEY",
     "x-partner-id": "YOUR-PARTNER-ID" // Required if you have multiple partner IDs
   }
   ```

**Note:**
If you're working with multiple partner IDs or are a platform serving multiple partners:

- Each Partner ID must be mapped to your API key
- Contact support to set up new ID mappings
  :::

## Environments

- **Stable**: A clone of our production environment, ideal for development and testing
- **Production**: Live environment for real transactions

**Note:**
If you previously used the Customer Digital Onboarding flow and the `partner` graph, your existing credentials will work with the `partner-platform` graph.

## Security Best Practices

1. Keep your API key secure and never expose it in client-side code
2. Use environment variables for storing credentials
3. Request new API keys if they are compromised
4. Use HTTPS for all API communications

## Interactive API Explorer

Explore the schema and run queries directly in the GraphQL playground:

- **Test**: [api.stable.life.li/graphql/partner](https://api.stable.life.li/graphql/partner)
- **Production**: [api.life.li/graphql/partner](https://api.life.li/graphql/partner)

Authenticate via the browser Basic Auth popup (leave username empty, enter your API key as password), then add your headers in the playground's Headers tab.

---

## Customer Digital Onboarding

URL: https://partner.life.li/integration-docs/customer-digital-onboarding

# Customer Digital Onboarding

Moving an existing Liechtenstein Life Invest integration to the Platform API? See [Migrating from Digital Onboarding](https://partner.life.li/integration-docs/platform-integrations/migrating-from-digital-onboarding).

Customer digital onboarding enables a seamless transition between creating an offer through our API with initial customer information (from your CRM or collected through your flows) and allowing customers to continue their journey in the Prosperity App. In the app, customers can:

- Edit/add information required for the offer
- Perform ID verification
- Submit the offer
- Once the policy is issued, access and manage their policy details

## Integration Steps

1. [Getting Started with GraphQL API](https://partner.life.li/integration-docs/customer-digital-onboarding/graphql-api)
2. [Integrating Single Sign-On](https://partner.life.li/integration-docs/customer-digital-onboarding/single-sign-on)
3. [Creating Offers with Customer Onboarding](https://partner.life.li/integration-docs/customer-digital-onboarding/creating-offers)

## Supported Products

- 🇩🇪 [Liechtenstein Life Invest](https://liechtensteinlife.com/en-DE/markets/de/products/liechtenstein-life-invest)
- 🇩🇪 ~~yourlife netto plus~~ — **deprecated**, no new integrations accepted

## Need Help?

If you need assistance with the integration or have questions about the onboarding flow, please reach out to our support team.

---

## Integrating Single Sign-On

URL: https://partner.life.li/integration-docs/customer-digital-onboarding/single-sign-on

# Integrating Single Sign-On

[Partner Life](https://partner.life.li) is our comprehensive portal for partners to manage contracts, support requests, customer information, and policy changes. This guide explains how to integrate your existing authentication system with Partner Life.

## Prerequisites

Before you begin, ensure you have:

- Your API Key
- You have your Partner ID (mentioned in your Partner Life invitation email) - (it looks like: `123000`, `23330-2`, etc.)
- You have the Partner IDs of your sub-brokers and employee accounts (found in their respective welcome email or in the colleague section of your Partner Life Account)

## Integration Steps

### 1. Basic Setup

First, set up access to our GraphQL API as described in the [GraphQL API Guide](https://partner.life.li/integration-docs/customer-digital-onboarding/graphql-api).

### 2. Generate Magic Links

Use the `createPartnerLifeMagicLink` mutation to generate direct access links to Partner Life:

```graphql
mutation Mutation($input: CreatePartnerLifeMagicLinkInput!) {
  createPartnerLifeMagicLink(input: $input) {
    __typename
    ... on PartnerLifeMagicLink {
      id
      magicLinkUrl
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

Example input:

```json
{
  "input": {
    "partnerId": "12345",
    "alreadyMultiFactorAuthenticated": true,
    "acceptPartnerLifeTermsAndConditions": true,
    "acknowledgePartnerLifePrivacyPolicy": true
  }
}
```

### 3. Authentication Flow

The basic authentication flow works as follows:

```mermaid
sequenceDiagram
    participant B as Broker/Employee
    participant Y as Your Software
    participant P as Partner API
    participant L as partner.life.li
    B->>+Y: Normal Authentication
    Y->>+P: trigger createPartnerLifeMagicLink API
    P-->>-Y: Response (with magic-link)
    Y->>+L: redirect to magic-link (automatically login user)
    L->>+L: Multi-factor Authentication Check (SMS/Passkey)
```

### 4. Multi-Factor Authentication

If your system already implements MFA, you can skip Partner Life's MFA check:

```mermaid
sequenceDiagram
    participant B as Broker/Employee
    participant Y as Your Software
    participant P as Partner API
    participant L as partner.life.li
    B->>+Y: Multi-factor authenticated
    Y->>+P: trigger createPartnerLifeMagicLink API<br>(setting alreadyMultiFactorAuthenticated as true)
    P-->>-Y: Response (with magic-link)
    Y->>+L: redirect to magic-link<br>(automatically login user, no MFA check)
```

### 5. Deep Linking

A magic link accepts a `redirect` parameter — a URL-encoded Partner Life path — so the advisor can land on a customer, on the product catalogue scoped to that customer, or on an offer, instead of on the dashboard. The paths are in [Deep Linking](https://partner.life.li/integration-docs/platform-integrations/single-sign-on#deep-linking); they work the same way for both APIs.

## Auto-Activation of Accounts

For new users with a Partner ID but no active account, you can automatically create their account by:

1. Setting both `acceptPartnerLifeTermsAndConditions` and `acknowledgePartnerLifePrivacyPolicy` to `true`
2. Ensuring the user has accepted:
   - [Terms and Conditions](https://partner.life.li/en/terms-and-conditions)
   - [Privacy Policy](https://partner.life.li/en/privacy-policy)

**Note:**

## Need Help?

If you don't have access to Partner Life or need assistance, contact [partner support](mailto:support@partner.life.li).

---

## Integration Options

URL: https://partner.life.li/integration-docs/

# Integration Options

Welcome to Prosperity's Partner Integration documentation. We offer several integration options to suit your needs:

## Customer Digital Onboarding

Create a partial offer through the API and let customers continue editing the offer through the app.

[Learn more about Customer Digital Onboarding →](https://partner.life.li/integration-docs/customer-digital-onboarding)

## Platform Integration

Create a complete offer with all required information, and get the policy documents (or continue working on it on Partner Life).

[Learn more about Platform Integration →](https://partner.life.li/integration-docs/platform-integrations)

## Embed Our Widgets

Add our calculators and onboarding widgets on your website, allow customers to start creating offers.

[Learn more about Embedded Widgets →](https://partner.life.li/integration-docs/widgets/embedded-calculator)

## BiPRO Integration

Receive policy documents in your broker management system via the BiPRO Norm 430 SOAP interface.

[Learn more about BiPRO Integration →](https://partner.life.li/integration-docs/bipro)

## AI-Assisted Integration

Using an AI coding assistant? Download our AI integration prompt or connect via llms.txt to let your AI build the integration with full schema knowledge.

[Set Up AI-Assisted Integration →](https://partner.life.li/integration-docs/ai-integration)

## Need Help?

If you need assistance with integration or have questions, please don't hesitate to reach out to our support team.

---

## Creating Offers and Generating Documents

URL: https://partner.life.li/integration-docs/platform-integrations/creating-offers

# Creating Offers and Generating Documents

## Prerequisites

- You have received your API Key (for stable and production environment)

## Creating Offers for New Customers

### Option 1: Download Application Document

If you already have information about the customer within your internal system, you can directly create an offer using the Partner Platform API mutation `createOffer`. This will:

1. Create the customer in our system
2. Generate a `Contract ID`
3. Allow you to request the application form PDF

```mermaid
sequenceDiagram
    participant Y as Your Software
    participant P as Partner API
    Y->>+P: Trigger createOffer API
    P-->>-Y: Response (with Contract ID)
    Y->>+P: Trigger offer(with Contract ID)
    P-->>-Y: Returns PDF download link (valid for 5 minutes)
    Y->>+P: Request and download the PDF
```

**Note:**
Wait approximately 30 seconds before requesting documents after creating an offer. This allows our systems to sync with the insurance system.

### Option 2: Partner Life Integration

You can also view the offer in Partner Life by using:

1. The `Contract ID` as a redirect parameter
2. A magic link generated using `createPartnerLifeMagicLink` mutation

The URL format will be:

```
https://partner.life.li/en/magic-link/<Magic Link Token>?redirect=%2Fmy%2Foffers%2F<Contract ID>
```

This will automatically log in the partner and redirect them to the offer page.

```mermaid
sequenceDiagram
    participant Y as Your Software
    participant P as Partner API
    participant L as Partner Life
    Y->>+P: Trigger createOffer API
    P-->>-Y: Response (with Contract ID)
    Y->>+P: Trigger createPartnerLifeMagicLink API
    P-->>-Y: Response (magic link)
    Y->>+L: Redirect to Partner Life
```

The same `redirect` parameter can send the advisor to the customer instead, or to the product catalogue scoped to them — so the offer is configured in Partner Life rather than assembled through `createOffer`, and nothing is created until they pick a product. See [Deep Linking](https://partner.life.li/integration-docs/platform-integrations/single-sign-on#deep-linking) for every destination.

### Option 3: End-to-End Submission via API

If you want to own the entire offer lifecycle inside your own software — collecting the signed application form, uploading identity documents, and submitting the offer for issuance — use the upload + submit mutations on top of Option 1. Nothing about Option 1 changes; this option simply continues from the downloaded PDF.

1. Create the offer with `createOffer` and download the application form PDF (Option 1)
2. Get the customer to sign the application form
3. Upload the signed form and the customer's identity document with `uploadDocument`
4. Submit the offer for issuance with `submitOffer`
5. (Optional) Track the offer lifecycle with `offerStatus` and respond to any `openReworks`

```mermaid
sequenceDiagram
    participant Y as Your Software
    participant P as Partner API
    Note over Y,P: Option 1: createOffer + download PDF
    Note over Y: Customer signs the application form
    Y->>+P: uploadDocument (SIGNED_APPLICATION_FORM)
    P-->>-Y: DocumentUploaded
    Y->>+P: uploadDocument (IDENTITY_VERIFICATION)
    P-->>-Y: DocumentUploaded
    Y->>+P: submitOffer(contractID)
    P-->>-Y: SubmittedOffer
```

See the [Uploading Required Documents](#uploading-required-documents) and [Submitting the Offer](#submitting-the-offer) sections below for the full mutation reference.

## Creating Offers for Existing Customers

For customers who already have a policy or offer where you are the broker, you can:

1. Use their customer ID (from our system)
2. Use their email address linked to existing policies

A customer you registered through [`createCustomer`](#registering-a-customer) counts as an existing customer from the moment it returns, before any offer exists.

```mermaid
sequenceDiagram
    participant Y as Your Software
    participant P as Partner API
    Y->>+P: Create offer with customer email/ID
    P-->>-Y: Response (with Contract ID)
    Y->>+P: Request application form
    P-->>-Y: PDF download link (valid for 5 minutes)
```

**Note:**
We will soon provide a way to fetch the list of customers associated with your Partner account (including sub-brokers) using the `customers` query with filters.

## API Reference

### Creating a New Offer

The `createOffer` mutation handles both new and existing customers. The operation includes comprehensive error handling:

```graphql
mutation CreateOffer($input: CreateOfferInput!) {
  createOffer(input: $input) {
    __typename
    ... on ErrorInterface {
      __typename
      message
    }
    ... on CreatedOffer {
      contractID
    }
    ... on InsuranceSystemError {
      reasons
    }
    ... on InputValidationError {
      invalidInput
      message
    }
  }
}
```

<details id="example-liechtenstein-life-invest">
<summary>Example: Liechtenstein Life Invest</summary>

**Note:**
`beneficiaries.deathBeneficiary.beneficiaryType` accepts `PARTNER`, `HEIRS` or `POLICY_HOLDER`, or supply `customBeneficiaries` to name the beneficiaries yourself.

`POLICY_HOLDER` is only accepted when the policy holder and the insured person are two different people. On an offer where one person holds both roles the death benefit would fall due to the person whose death triggers it, so the request returns `InputValidationError` with `invalidInput: BENEFICIARIES_DEATH_BENEFICIARY_TYPE_NOT_ALLOWED`.

```json
{
  "input": {
    "liechtensteinLifeInvest": {
      "associatedPersons": [
        {
          "role": [
            "MAILING",
            "INSURED_PERSON",
            "POLICY_HOLDER",
            "PAYER",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "2000-04-06",
              "maritalStatus": "SINGLE",
              "nationality": "DE",

              "profession": "Lawyer",
              "occupation": "Lawyer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "berlin",
                "street": "Frankfuter-Alle",
                "zip": "10367",
                "houseNumber": "23A",
                "streetAppendix": "8th Cross"
              },
              "identification": {
                "birthPlace": "Tokyo",
                "documentNumber": "AR12333323232",
                "documentType": "PASSPORT",
                "issueDate": "2025-01-01",
                "issuedBy": "Govt of Japan",
                "validUntil": "2026-01-01"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "premiumDynamicPercentage": 10,
        "ageUntilPremiumIsPaid": 73,
        "additionalPayment": 1000000,
        "ageWhenPolicyEnds": 82,
        "monthlyPremium": 10000,
        "startDate": "2025-05-01",
        "language": "DE_DE",
        "deathCoveragePercentage": 100,
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "IE0004766675",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "DYNAMIC",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": ["TOBACCO_INDUSTRY"],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        }
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 100000,
        "totalMonthlyNetIncome": 400000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "criticalIllnessDetails": null,
        "weight": 47,
        "height": 156
      }
    }
  }
}
```

</details>

<details id="example-liechtenstein-life-wealth">
<summary>Example: Liechtenstein Life Wealth</summary>

```json
{
  "input": {
    "liechtensteinLifeWealth": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "INSURED_PERSON",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "policyHolder@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "1976-04-06",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "profession": "Lawyer",
              "occupation": "Lawyer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "berlin",
                "street": "Frankfuter-Alle",
                "zip": "10367",
                "houseNumber": "23A",
                "streetAppendix": "8th Cross"
              },
              "identification": {
                "birthPlace": "Tokyo",
                "documentNumber": "AR12333323232",
                "documentType": "PASSPORT",
                "issueDate": "2025-01-01",
                "issuedBy": "Govt of Japan",
                "validUntil": "2026-01-01"
              }
            }
          }
        },
        {
          "role": ["ADDITIONAL_INSURED_PERSON"],
          "person": {
            "newCustomer": {
              "email": "additionalInduredPerson@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "2000-04-06",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "profession": "Lawyer",
              "occupation": "Lawyer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "berlin",
                "street": "Frankfuter-Alle",
                "zip": "10367",
                "houseNumber": "23A",
                "streetAppendix": "8th Cross"
              }
            }
          }
        },
        {
          "role": ["ADDITIONAL_POLICY_HOLDER"],
          "person": {
            "newCustomer": {
              "email": "additionalPolicyHolder@example.com",
              "firstName": "Jane",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "1978-04-06",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "profession": "Lawyer",
              "occupation": "Lawyer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "berlin",
                "street": "Frankfuter-Alle",
                "zip": "10367",
                "houseNumber": "23A",
                "streetAppendix": "8th Cross"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "premiumDynamicPercentage": 10,
        "ageUntilPremiumIsPaid": 73,
        "additionalPayment": 1000000,
        "ageWhenPolicyEnds": 73,
        "regularPremium": 50000,
        "startDate": "2025-07-01",
        "language": "DE_DE",
        "minimumDeathBenefit": "TAX_MINIMUM",
        "additionalDeathBenefit": 150,
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "IE0004766675",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "DYNAMIC",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": ["TOBACCO_INDUSTRY"],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        },
        "termFix": {
          "events": "BIRTH_OF_CHILD",
          "term": "2031-01-01",
          "funds": [
            {
              "id": "IE0004766675",
              "percentage": 100
            }
          ]
        },
        "premiumMode": null,
        "payoutPlan": {
          "schedules": [
            {
              "start": "2030-09-01",
              "end": "2034-09-01",
              "amount": 100000,
              "frequency": "MONTHLY"
            },
            {
              "start": "2035-09-01",
              "end": "2037-09-01",
              "amount": 100000,
              "frequency": "MONTHLY"
            }
          ],
          "iban": "DE75512108001245126199",
          "accountHolder": "John Doe"
        },
        "maturityManagement": true,
        "deathCoveragePayout": "FIRST_TO_DIE",
        "additionalPolicyHolderPercentage": 50
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 100000,
        "totalMonthlyNetIncome": 400000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "hasNoMedicalConditions": true,
        "hasNoMedicalConsultation": true,
        "criticalIllnessDetails": null,
        "weight": 47,
        "height": 156
      },
      "additionalInsuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "hasNoMedicalConditions": true,
        "hasNoMedicalConsultation": true,
        "criticalIllnessDetails": null,
        "weight": 47,
        "height": 156
      },
      "beneficiaries": {
        "lifeBeneficiary": {
          "beneficiaryType": "POLICY_HOLDER"
        },
        "deathBeneficiary": {
          "beneficiaryType": "PARTNER"
        },
        "isDeathBeneficiaryIrrevocable": true,
        "beneficiaryRights": "REVOCABLE",
        "termFixRights": "REVOCABLE"
      }
    }
  }
}
```

</details>

<details id="example-prosperity-plus-germany">
<summary>Example: Prosperity Plus Germany</summary>

**Note:**
`beneficiaries.deathBeneficiary.beneficiaryType` accepts `PARTNER` or `POLICY_HOLDER`, or supply `customBeneficiaries` to name the beneficiaries yourself.

`POLICY_HOLDER` is only accepted when the policy holder and the insured person are two different people. On an offer where one person holds both roles the death benefit would fall due to the person whose death triggers it, so the request returns `InputValidationError` with `invalidInput: BENEFICIARIES_DEATH_BENEFICIARY_TYPE_NOT_ALLOWED`.

```json
{
  "input": {
    "prosperityPlusGermany": {
      "associatedPersons": [
        {
          "role": [
            "MAILING",
            "INSURED_PERSON",
            "POLICY_HOLDER",
            "PAYER",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "2000-04-06",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "profession": "Lawyer",
              "occupation": "Lawyer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "berlin",
                "street": "Frankfuter-Alle",
                "zip": "10367",
                "houseNumber": "23A",
                "streetAppendix": "8th Cross"
              },
              "identification": {
                "birthPlace": "Tokyo",
                "documentNumber": "AR12333323232",
                "documentType": "PASSPORT",
                "issueDate": "2025-01-01",
                "issuedBy": "Govt of Japan",
                "validUntil": "2026-01-01"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "premiumDynamicPercentage": 10,
        "ageUntilPremiumIsPaid": 73,
        "additionalPayment": 1000000,
        "ageWhenPolicyEnds": 82,
        "monthlyPremium": 10000,
        "maturityManagement": true,
        "premiumWaiver": true,
        "startDate": "2025-08-01",
        "language": "DE_DE",
        "deathCoveragePercentage": 100,
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "IE0004766675",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "DYNAMIC",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": ["TOBACCO_INDUSTRY"],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        },
        "brokerageFeePayoutMethod": "GROSS"
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 100000,
        "totalMonthlyNetIncome": 400000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "criticalIllnessDetails": null,
        "weight": 47,
        "height": 156
      }
    }
  }
}
```

</details>

<details id="example-liechtenstein-life-pension">
<summary>Example: Liechtenstein Life Pension (Basisrente)</summary>

**Note:**
- **Beneficiaries**: Death beneficiary is restricted to `PARTNER` only — this is a regulatory requirement for German Basisrente products (Schicht 1)
- **No life beneficiary**: Life beneficiaries are not supported
- **No premium dynamic**: `premiumDynamicPercentage` is not supported — omit this field
- **Guarantee options**: `NO_GUARANTEE`, `SELECT_50`, `SELECT_80`
- **`lifelong_pension_purpose`**: Always enforced as `true` regardless of the `goals.longTerm` input value

```json
{
  "input": {
    "liechtensteinLifePension": {
      "associatedPersons": [
        {
          "role": [
            "MAILING",
            "INSURED_PERSON",
            "POLICY_HOLDER",
            "PAYER",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "gender": "MALE",
              "dateOfBirth": "1985-06-15",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "profession": "Software Engineer",
              "occupation": "Software Engineer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "DE",
                    "id": "96618720548"
                  }
                ]
              },
              "phoneNumber": "+4900000000",
              "address": {
                "country": "DE",
                "city": "Berlin",
                "street": "Musterstraße",
                "zip": "10115",
                "houseNumber": "1"
              },
              "identification": {
                "birthPlace": "Berlin",
                "documentNumber": "C01X00T478",
                "documentType": "ID_CARD",
                "issueDate": "2020-01-15",
                "issuedBy": "Stadt Berlin",
                "validUntil": "2030-01-15"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "ageUntilPremiumIsPaid": 67,
        "additionalPayment": 0,
        "ageWhenPolicyEnds": 67,
        "monthlyPremium": 10000,
        "maturityManagement": true,
        "premiumWaiver": true,
        "guarantee": "SELECT_80",
        "startDate": "2026-09-01",
        "language": "DE_DE",
        "deathCoveragePercentage": 0,
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "LU0360863863",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": true,
            "flexibility": false,
            "longTerm": true
          },
          "rebalancingType": "NORMAL",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": [],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        },
        "absoluteReductionFundAdministrationCost": 0.5
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 150000,
        "totalMonthlyNetIncome": 500000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "criticalIllnessDetails": null,
        "weight": 80,
        "height": 180
      },
      "beneficiaries": {
        "deathBeneficiary": "PARTNER",
        "isDeathBeneficiaryIrrevocable": false
      }
    }
  }
}
```

</details>

<details id="example-value-invest-vwl">
<summary>Example: Value Invest VWL (employer-funded)</summary>

**Note:**
**VWL** (Vermögenswirksame Leistungen) is a German employer-funded capital-forming benefit. The employer pays a fixed monthly contribution into a contract held by the employee.

- **Exactly two associated persons required**:
  - **Employer (corporate entity)** — Roles: `[PAYER]` only. Provide either `existingCustomer` (employer already onboarded) or `newCompanyCustomer` (create the employer inline as part of the offer). `newCustomer` is rejected for PAYER because it cannot represent a company.
  - **Employee** — the contract holder. Roles: `[POLICY_HOLDER, INSURED_PERSON, MAILING, ECONOMIC_INTEREST]` — all four, exactly. Employee can be a new or existing individual customer. `newCompanyCustomer` is rejected for non-PAYER roles.
- **The employer pays the premium**: `customerFinancialStatus.paymentMethod` describes the **employer's** payment arrangement, not the employee's. `{ "wireTransfer": true }` — the usual choice — means the employer transfers the capital-forming contribution, typically as a standing order, and no bank details are collected from anyone. `directDebit` places the SEPA mandate on the **employer's** account. Never send employee bank details on a VWL offer. Who arranges that standing order is your call, and one of the two answers leaves a manual step to you — see [who sets the standing order up](#value-invest-vwl-who-sets-the-standing-order-up).
- **Onboard the employer once**: each employer should be created in our system once and re-used across all their employees' offers. Use `newCompanyCustomer` on the first offer for a new employer, then reference the same employer via `existingCustomer.byEmail` on subsequent offers.
- **Tariff**: `value invest VWL 2022` (fixed)
- **Currency**: EUR (amounts in cents — `4000` = EUR 40.00, the typical VWL contribution)
- **Language**: `DE_DE` only — VWL is a German-market product
- **Premium limits**: the regular premium per year — `monthlyPremium` times the number of payments per year, so EUR 250 monthly at most — must be between EUR 168 and EUR 3,000. `additionalPayment` must be `0` or at least EUR 50. The regular premium per year plus `additionalPayment` must not exceed EUR 3,000. For example, EUR 200 monthly (EUR 2,400 a year) leaves room for an `additionalPayment` of EUR 600 at most. An offer outside these limits fails with `PRODUCT_CONFIGURATION_VWL_REGULAR_PREMIUM_OUT_OF_RANGE`, `PRODUCT_CONFIGURATION_VWL_ADDITIONAL_PAYMENT_BELOW_MINIMUM` or `PRODUCT_CONFIGURATION_VWL_TOTAL_PREMIUM_EXCEEDS_LIMIT`. The limits are not checked for `premiumMode: 0`.
- **Required**: `personalNumber` — the employer's internal payroll identifier for the employee
- **No premium dynamic**: `premiumDynamicPercentage` is not part of the schema
- **Health questions**: `insuredPersonsHealthStatus` is optional, but send it whenever you collect the answers. The insurance system only asks the questions above a limit, and it is replacing the rule that sets it. The new rule looks at the death benefit: (the sum of all premiums over the term + `additionalPayment`) × `deathCoveragePercentage` reaching EUR 35,000. Not every environment applies it yet, and some still ask above a yearly premium (the amount printed next to the question on the application form). When the questions apply and the answers are missing, the offer can be created but cannot be signed. `hasCriticalIllness` is the form's combined question about diseases and medication taken for longer than 4 weeks (`true` needs `criticalIllnessDetails` with `type`, `period`, `hasRecovered`, `medicalInstitutionName` and, if any, `medication`). Also send `height` and `weight`, and `smoking` and `medicalPractitionerInformation`, which are required outside production. We never answer a health question on the employee's behalf.
- **Smoking question in production**: the production application form has no smoking question yet. There the API accepts `smoking` and `medicalPractitionerInformation` but does not pass them on to the insurance system. Once the question is mandatory in production, we will pass them on. Send both in every environment, so your integration needs no change then.
- **Guarantee options**: `NO_GUARANTEE`, `SELECT_50`, `SELECT_80`
- **Application kind**: `capitalAccumulationBenefit` sets the box the application form ticks under "Antrag": `NEW` (_Neuantrag_), `INCREASE` (an increase of the capital-forming benefits) or `CHANGE` (a change of how they are invested). It defaults to `NEW`, so calls that do not send it keep working.
- **Employee's birth place and country**: send `birthPlace` (the city only, e.g. `Berlin`) and `birthCountry` on the employee's `newCustomer`. The application form prints "Geburtsort" and "Geburtsland" from these two fields. It does not print `identification.birthPlace`, which records the place exactly as written on the identification document.
- **Occupation**: the application form prints `occupation` as "Ausgeübter Beruf" and prints `profession, occupation` together as "Abteilung". When you omit `occupation`, we use the `profession`, so "Abteilung" then repeats it. Send a distinct `occupation` to avoid that.
- **Death beneficiary**: `beneficiaries.deathBeneficiary` takes `{ "beneficiaryType": "PARTNER" }` (the default) or `{ "customBeneficiaries": [...] }`. The application form has no option for the legal heirs: to name them, list them in `customBeneficiaries`. Their `allotmentPercentage` values must add up to exactly 100.

The example below shows the most common shape: a brand-new employer (`newCompanyCustomer`) plus a brand-new employee (`newCustomer`) on the same request. For subsequent offers tied to the **same** employer, swap the `PAYER` entry to `{ "existingCustomer": { "byEmail": { "email": "hr@acme.example" } } }` — keep the rest unchanged.

```json
{
  "input": {
    "valueInvestVWL": {
      "associatedPersons": [
        {
          "role": ["PAYER"],
          "person": {
            "newCompanyCustomer": {
              "name": "Acme GmbH",
              "additionalName": "Acme Trading",
              "contactName": "HR Department",
              "legalForm": "GmbH",
              "financialInstitution": false,
              "email": "hr@acme.example",
              "mobilePhone": "+4915000000000",
              "landline": "+493012345678",
              "address": {
                "country": "DE",
                "city": "Berlin",
                "street": "Unter den Linden",
                "zip": "10117",
                "houseNumber": "1"
              },
              "taxInformation": {
                "taxLiableInUSA": false,
                "vatNumber": "DE123456789",
                "taxIDCountry": "DE"
              }
            }
          }
        },
        {
          "role": [
            "POLICY_HOLDER",
            "INSURED_PERSON",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "employee@example.com",
              "firstName": "Anna",
              "lastName": "Schmidt",
              "gender": "FEMALE",
              "dateOfBirth": "1992-03-14",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "birthPlace": "Munich",
              "birthCountry": "DE",
              "profession": "Mechatronics Engineer",
              "occupation": "Mechatronics Engineer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  { "country": "DE", "id": "12345678911" }
                ]
              },
              "phoneNumber": "+4901701234567",
              "address": {
                "country": "DE",
                "city": "Munich",
                "street": "Leopoldstraße",
                "zip": "80802",
                "houseNumber": "12"
              },
              "identification": {
                "birthPlace": "Munich",
                "documentNumber": "L01XY12345",
                "documentType": "ID_CARD",
                "issueDate": "2022-01-15",
                "issuedBy": "Stadt München",
                "validUntil": "2032-01-15"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "personalNumber": "EMP-2026-0042",
        "startDate": "2026-06-01",
        "language": "DE_DE",
        "ageWhenPolicyEnds": 67,
        "monthlyPremium": 4000,
        "additionalPayment": 0,
        "guarantee": "SELECT_80",
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            { "id": "AT0000A08LD9", "percentage": 100 }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": false,
            "longTerm": true
          },
          "rebalancingType": "NORMAL",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": [],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        }
      },
      "customerFinancialStatus": {
        "moneyOrigin": "EARNED_INCOME",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 180000,
        "totalMonthlyNetIncome": 320000
      },
      "beneficiaries": {
        "deathBeneficiary": { "beneficiaryType": "PARTNER" },
        "isDeathBeneficiaryIrrevocable": false
      }
    }
  }
}
```

</details>

<details id="example-your-life-netto-plus">
<summary>Example: Your Life Netto Plus (Deprecated)</summary>

**Note:**
**yourlife netto plus is deprecated.** New integrations are no longer being accepted for this product. Existing integrations remain supported, but new partners should use one of the other Germany products (Liechtenstein Life Invest, Liechtenstein Life Wealth, Liechtenstein Life Pension, Prosperity Plus Germany) instead. Contact your integration partner manager if you have questions about migrating off YLN+.

```json
{
  "input": {
    "yourLifeNettoPlus": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "INSURED_PERSON",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "Max",
              "lastName": "Mustermann",
              "dateOfBirth": "1990-01-15",
              "gender": "MALE",
              "maritalStatus": "SINGLE",
              "nationality": "DE",
              "address": {
                "street": "Musterstraße",
                "houseNumber": "1",
                "zip": "10115",
                "city": "Berlin",
                "country": "DE"
              },
              "mobilePhone": "+491701234567",
              "profession": "Software Engineer",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "id": "12345678911",
                    "country": "DE"
                  }
                ]
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "startDate": "2026-04-01",
        "ageWhenPolicyEnds": 67,
        "monthlyPremium": 10000,
        "additionalPayment": 0,
        "deathCoveragePercentage": 100,
        "investmentStrategy": {
          "goals": {
            "longTerm": true,
            "taxBenefit": false,
            "flexibility": true
          },
          "sustainabilityDetails": {
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE",
            "percentage": 0
          },
          "fundSelection": [
            {
              "id": "LU0360863863",
              "percentage": 100
            }
          ],
          "riskLevel": "MEDIUM"
        }
      },
      "customerFinancialStatus": {
        "policyReason": "PRIVATE_PENSION",
        "moneyOrigin": "EARNED_INCOME",
        "totalMonthlyNetIncome": 500000,
        "totalMonthlyExpenses": 300000,
        "paymentMethod": {
          "directDebit": {
            "iban": "DE89370400440532013000",
            "accountHolder": "Max Mustermann"
          }
        }
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false
      }
    }
  }
}
```

</details>

<details>
<summary>Example: Using Existing Customer</summary>

```json
{
  "input": {
    "liechtensteinLifeInvest": {
      "associatedPersons": [
        {
          "role": [
            "MAILING",
            "INSURED_PERSON",
            "POLICY_HOLDER",
            "PAYER",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "sampleEmailAddressNetto4@test.com"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "additionalPayment": 1000000,
        "ageWhenPolicyEnds": 82,
        "monthlyPremium": 10000,
        "startDate": "2025-05-01",
        "language": "DE_DE",
        "deathCoveragePercentage": 100,
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "IE0004766675",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "DYNAMIC",
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "SIGNIFICANT",
            "percentage": 0,
            "topicsToExclude": ["TOBACCO_INDUSTRY"],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "NO_PRE_EXISTING_KNOWLEDGE_BUT_EDUCATED_BY_BROKER"
          }
        }
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "paymentMethod": {
          "wireTransfer": true
        },
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 100000,
        "totalMonthlyNetIncome": 400000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null
      },
      "insuredPersonsHealthStatus": {
        "hasCriticalIllness": false,
        "criticalIllnessDetails": null,
        "weight": 47,
        "height": 156
      }
    }
  }
}
```

</details>

<details id="example-prosperity-3a-swiss-pillar-3a">
<summary>Example: Prosperity 3A (Swiss Pillar 3a)</summary>

```json
{
  "input": {
    "prosperity3A": {
      "associatedPersons": [
        {
          "role": [
            "MAILING",
            "INSURED_PERSON",
            "POLICY_HOLDER",
            "PAYER",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "James",
              "lastName": "Jones",
              "gender": "MALE",
              "dateOfBirth": "1975-07-21",
              "maritalStatus": "MARRIED",
              "nationality": "CH",
              "profession": "IT",
              "occupation": "Analyst",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "CH",
                    "id": "756.9217.0769.85"
                  }
                ]
              },
              "phoneNumber": "+41000000000",
              "address": {
                "country": "CH",
                "city": "Ruggell",
                "street": "Industriering",
                "zip": "9491",
                "houseNumber": "3",
                "streetAppendix": null
              },
              "identification": {
                "birthPlace": "Zürich",
                "documentNumber": "P123457689",
                "documentType": "PASSPORT",
                "issueDate": "2014-03-21",
                "issuedBy": "Zurich Tax Hall",
                "validUntil": "2028-03-21"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "startDate": "2026-05-01",
        "ageWhenPolicyEnds": 65,
        "monthlyPremium": 15000,
        "premiumMode": "MONTHLY",
        "premiumDynamicPercentage": 3,
        "additionalPayment": 100000,
        "transferExisting3APolicy": {
          "sourceType": "BANK",
          "amount": 500000,
          "name": "UBS AG",
          "address": "Bahnhofstrasse 45",
          "zip": "8001",
          "city": "Zürich"
        },
        "guarantee": "SELECT_50",
        "investmentStrategy": {
          "riskLevel": "MEDIUM",
          "fundSelection": [
            {
              "id": "LU0070176184",
              "percentage": 60
            },
            {
              "id": "LLA030",
              "percentage": 40
            }
          ],
          "goals": {
            "taxBenefit": true,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "NORMAL",
          "lowRiskInvestment": false,
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "NORMAL",
            "percentage": 0,
            "topicsToExclude": [],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE"
          }
        },
        "coverage": {
          "type": "CHOSEN",
          "amount": 1444000
        },
        "crossBorderTariffApplicable": false,
        "durationOverRetirement": false,
        "maturityManagement": true,
        "language": "DE_CH"
      },
      "insuredPersonsHealthStatus": {
        "worksAsSelfEmployed": false,
        "employmentWorkload": 100,
        "height": 180,
        "weight": 75,
        "existingInsuranceContract": {
          "hasExistingInsuranceContract": false
        },
        "hasAggravatedTermsContract": false,
        "additionalHealthRisk": {
          "hasAdditionalRisks": false
        },
        "knownDiseases": {
          "hasHadKnownDiseases": false
        },
        "hasExistingDisabilities": false,
        "medication": {
          "hasBeenRegularlyMedicated": false
        },
        "hospitalization": {
          "hasBeenHospitalized": false
        },
        "hasAnnuity": false,
        "drugAbuse": {
          "hasBeenTreatedForDrugAbuse": false
        },
        "smoking": {
          "hasSmoked": false
        },
        "hasHIV": false,
        "medicalPractitionerInformation": "Dr. Hans Müller, Bahnhofstrasse 10, 8001 Zürich"
      },
      "customerFinancialStatus": {
        "moneyOrigin": "SAVINGS",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 300000,
        "totalMonthlyNetIncome": 800000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null,
        "differentWealthOrigin": false,
        "paymentMethod": {
          "wireTransfer": true
        }
      }
    }
  }
}
```

**Note:**
- **All amounts are in the smallest monetary unit** — Rappen for CHF (1 CHF = 100 Rappen). For example, `15000` = CHF 150.00, `1000000` = CHF 10,000.00
- **Disability annuity** — requires `premiumWaiver` to be set. The `jobClass` and `jobRisk` must be a valid pair from the [job classes reference](https://partner.life.li/integration-docs/platform-integrations/job-classes)
- **Health questionnaire** — required when `premiumWaiver` or `disabilityAnnuity` is set. Uses `insuredPersonsHealthStatus` with Swiss-specific fields. Several fields are structured objects containing a boolean flag and optional detail fields (required when the flag is `true`): `existingInsuranceContract`, `additionalHealthRisk`, `knownDiseases`, `medication`, `hospitalization`, `drugAbuse`, `smoking`. For example, if the person has been hospitalized: `"hospitalization": { "hasBeenHospitalized": true, "hospitalizationDetails": "Appendectomy, March 2022" }`.
- **No beneficiaries** — the insurance system handles beneficiary defaults automatically
- **Payment method (optional)** — use `paymentMethod` in `customerFinancialStatus` to specify a Swiss-specific payment method. Available options:
  - `{ "wireTransfer": true }` — bank transfer
  - `{ "lsvPlus": { "iban": "CH...", "bic": "UBSWCHZH80A", "signatureDate": "2026-03-01" } }` — LSV+ (Swiss direct debit)
  - `{ "esr": true }` — ESR (Swiss payment slip)
  - If omitted, the insurance system auto-assigns a standing order
- **Risk level required** — the selected risk level must match the risk class of the selected funds
- **Currency is CHF** — Swiss pillar 3a products use Swiss Francs
- **Age range 60–70** — Swiss retirement age constraints apply (`ageWhenPolicyEnds` must be between 60 and 70)
- **Coverage block** — uses `coverage: { type, amount }` instead of `deathCoveragePercentage`
- **Guarantee** — optional capital guarantee at maturity (`NO_GUARANTEE`, `SELECT_50`, `SELECT_80`, `SELECT_90`, `SELECT_100`, or omit for none)
- **3A transfer** — use `transferExisting3APolicy` to transfer from an existing 3a account. Specify `sourceType` (`BANK` or `INSURANCE`), `amount`, and institution details. Insurance-to-insurance transfers automatically zero acquisition costs.
- **Premium mode** — use the `Prosperity3APremiumMode` enum (`ANNUALLY`, `SEMI_ANNUALLY`, `QUARTERLY`, `MONTHLY`). Defaults to `MONTHLY` if omitted.
- **Coverage type** — `CHOSEN` requires an `amount`; `PERCENTAGE` gives 101% of actuarial reserve (no amount needed)
- **Low risk investment** — `lowRiskInvestment` on the investment strategy is required and used by the insurance system to validate fund selection
- **Language** — use the `Prosperity3AContractLanguage` enum (`DE_DE`, `DE_CH`, `FR_FR`, `IT_IT`). Defaults to `DE_DE` if omitted.

</details>

<details id="example-prosperity-plus-swiss-pillar-3b">
<summary>Example: Prosperity Plus (Swiss Pillar 3b)</summary>

```json
{
  "input": {
    "prosperityPlus": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "INSURED_PERSON",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "newCustomer": {
              "email": "sampleEmailAddress@example.com",
              "firstName": "James",
              "lastName": "Jones",
              "gender": "MALE",
              "dateOfBirth": "1985-07-21",
              "maritalStatus": "MARRIED",
              "nationality": "CH",
              "profession": "IT",
              "occupation": "Analyst",
              "taxIdentification": {
                "taxLiableInUSA": false,
                "residencies": [
                  {
                    "country": "CH",
                    "id": "756.9217.0769.85"
                  }
                ]
              },
              "phoneNumber": "+41000000000",
              "address": {
                "country": "CH",
                "city": "Ruggell",
                "street": "Industriering",
                "zip": "9491",
                "houseNumber": "3",
                "streetAppendix": null
              },
              "identification": {
                "birthPlace": "Zürich",
                "documentNumber": "P123457689",
                "documentType": "PASSPORT",
                "issueDate": "2014-03-21",
                "issuedBy": "Zurich Tax Hall",
                "validUntil": "2028-03-21"
              }
            }
          }
        }
      ],
      "productConfiguration": {
        "startDate": "2026-05-01",
        "ageWhenPolicyEnds": 65,
        "monthlyPremium": 10000,
        "premiumMode": "MONTHLY",
        "additionalPayment": 0,
        "hasSecondPillar": true,
        "guarantee": "NO_GUARANTEE",
        "investmentStrategy": {
          "riskLevel": "HIGH",
          "fundSelection": [
            {
              "id": "LU1894683009",
              "percentage": 100
            }
          ],
          "goals": {
            "taxBenefit": false,
            "flexibility": true,
            "longTerm": true
          },
          "rebalancingType": "NONE",
          "lowRiskInvestment": false,
          "sustainabilityDetails": {
            "environmentalAndSocialInvestmentFocusLevel": "NORMAL",
            "percentage": 0,
            "topicsToExclude": [],
            "topicsToInclude": [],
            "customerKnowledgeStatus": "HAS_PRE_EXISTING_KNOWLEDGE"
          }
        },
        "coverage": {
          "type": "CHOSEN",
          "amount": 1000000
        },
        "crossBorderTariffApplicable": false,
        "maturityManagement": true,
        "postDelivery": false,
        "lifeBeneficiary": {
          "beneficiaryType": "POLICY_HOLDER"
        },
        "deathBeneficiary": {
          "beneficiaryType": "DEFAULT"
        },
        "language": "DE_CH"
      },
      "customerFinancialStatus": {
        "moneyOrigin": "EARNED_INCOME",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 140000,
        "totalMonthlyNetIncome": 200000,
        "moneyOriginOtherText": null,
        "policyReasonOtherText": null,
        "differentWealthOrigin": false,
        "paymentMethod": {
          "wireTransfer": true
        }
      }
    }
  }
}
```

**Note:**
- **No tax benefits** — unlike 3A, Prosperity Plus (3b) does not offer tax-deductible contributions, but provides more flexibility
- **All amounts are in the smallest monetary unit** — Rappen for CHF (1 CHF = 100 Rappen). For example, `10000` = CHF 100.00, `1000000` = CHF 10,000.00
- **Beneficiaries** — supports both `lifeBeneficiary` and `deathBeneficiary` in `productConfiguration`:
  - **Life beneficiary**: `{ "beneficiaryType": "POLICY_HOLDER" }` (default) or provide `customBeneficiaries` array (each entry requires `firstName`, `lastName`, `dateOfBirth`, `gender`, `address`, `allotmentPercentage`)
  - **Death beneficiary**: `{ "beneficiaryType": "DEFAULT" }` (heirs) or custom with `customBeneficiaries` array
- **`hasSecondPillar`** — boolean indicating whether the customer has a second pillar pension
- **`postDelivery`** — boolean for postal delivery of documents
- **No 3A transfer** — `transferExisting3APolicy` is not available (pillar 3b is separate from 3a)
- **No `durationOverRetirement`** — this field is 3A-specific
- **Age range 18–99** — broader than 3A's 60–70 retirement constraint for `ageWhenPolicyEnds`
- **Payment method** — only `wireTransfer` and `esr` are available (no LSV+ direct debit)
- **Premium mode** — use the `ProsperityPlusPremiumMode` enum (`ANNUALLY`, `SEMI_ANNUALLY`, `QUARTERLY`, `MONTHLY`)
- **Disability annuity** — requires `premiumWaiver` to be set. The `jobClass` and `jobRisk` must be a valid pair from the [job classes reference](https://partner.life.li/integration-docs/platform-integrations/job-classes)
- **Health questionnaire** — required when `premiumWaiver` or `disabilityAnnuity` is set in `productConfiguration`. Uses the same structure as Prosperity 3A (`insuredPersonsHealthStatus`)
- **Guarantee** — optional capital guarantee at maturity (`NO_GUARANTEE`, `SELECT_50`, `SELECT_80`, `SELECT_90`, `SELECT_100`)
- **Coverage type** — `CHOSEN` requires an `amount`; `PERCENTAGE` gives 101% of actuarial reserve (no amount needed)
- **Language** — use the `ProsperityPlusContractLanguage` enum (`DE_DE`, `DE_CH`, `FR_FR`, `IT_IT`)
- **Currency is CHF** — Swiss pillar 3b products use Swiss Francs

</details>

<details id="example-prosperity-duo">
<summary>Example: Prosperity Duo (Swiss Pillar 3b)</summary>

Use `prosperityDuo` for a holder saving for a separate relative aged 16–60 at policy start. The holder carries `POLICY_HOLDER`, `PAYER`, `MAILING` and `ECONOMIC_INTEREST`; the relative carries `INSURED_PERSON` only. The holder supplies `policyHolderHealthStatus`, and the holder's age determines policy and payment terms.

This example references a synthetic holder born in 1985 and a relative born in 1990. Replace the customer references, date and fund selection before sending a request. Collect all declarations from the customer; the example answers are not defaults.

```json
{
  "input": {
    "prosperityDuo": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-holder@example.com"
              }
            }
          }
        },
        {
          "role": [
            "INSURED_PERSON"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-relative@example.com"
              }
            }
          }
        }
      ],
      "customerFinancialStatus": {
        "hasSwissIncome": true,
        "moneyOrigin": "EARNED_INCOME",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 300000,
        "totalMonthlyNetIncome": 600000,
        "differentWealthOrigin": false
      },
      "policyHolderHealthStatus": {
        "worksAsSelfEmployed": false,
        "employmentWorkload": 100,
        "height": 180,
        "weight": 75,
        "existingInsuranceContract": {
          "hasExistingInsuranceContract": false
        },
        "hasAggravatedTermsContract": false,
        "additionalHealthRisk": {
          "hasAdditionalRisks": false
        },
        "knownDiseases": {
          "hasHadKnownDiseases": false
        },
        "hasExistingDisabilities": false,
        "medication": {
          "hasBeenRegularlyMedicated": false
        },
        "hospitalization": {
          "hasBeenHospitalized": false
        },
        "hasAnnuity": false,
        "drugAbuse": {
          "hasBeenTreatedForDrugAbuse": false
        },
        "smoking": {
          "hasSmoked": false
        },
        "hasHIV": false,
        "medicalPractitionerInformation": "Synthetic practitioner, Teststrasse 2, 8001 Zürich"
      },
      "productConfiguration": {
        "startDate": "2026-11-01",
        "ageWhenPolicyEnds": 66,
        "regularPremium": 20000,
        "premiumMode": "MONTHLY",
        "additionalPayment": 100000,
        "guarantee": "SELECT50",
        "maturityManagement": true,
        "language": "DE_CH",
        "investmentStrategy": {
          "riskLevel": "HIGH",
          "fundSelection": [
            {
              "id": "LU0070176184",
              "percentage": 100
            }
          ],
          "goals": {
            "longTerm": true,
            "taxBenefit": false,
            "flexibility": true
          },
          "lowRiskInvestment": false,
          "rebalancingType": "NONE",
          "sustainabilityDetails": {
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE",
            "percentage": 0,
            "topicsToInclude": [],
            "topicsToExclude": []
          }
        }
      }
    }
  }
}
```

**Note:**
- Holder entry age: 18–75; relative entry age: 16–60; policy end by holder age 85.
- Minimum policy/payment terms: ten/five years. Annual premiums must be at least CHF 1,200, with an agreed regular-premium sum of at least CHF 12,000.
- `additionalPayment` is 0 or at least CHF 500. Regular premiums are amounts per payment, in CHF minor units.
- Retrieve funds with `availableFunds(product: PROSPERITY_DUO)`. Select50/80 require twenty policy/payment years; Select100 requires thirty. Any guarantee requires `maturityManagement: true`.
- Optional holder premium waiver requires entry age at most 60 and a waiting period of 6, 12 or 24 months. Relative disability annuities are not exposed.
- Follow the [shared Swiss requirements](#swiss-savings-requirements), including the environment-specific health questions and consultation protocol.

</details>

<details id="example-prosperity-junior">
<summary>Example: Prosperity Junior (Swiss Pillar 3b)</summary>

Use `prosperityJunior` for an adult holder saving for a separate child aged 0–15 at policy start. The holder carries `POLICY_HOLDER`, `PAYER`, `MAILING` and `ECONOMIC_INTEREST`; the child carries `INSURED_PERSON` only. The holder supplies `policyHolderHealthStatus`; these are not the child's health answers. Policy and payment terms use the holder's age.

This example references a synthetic holder born in 1985 and a child born in 2018. Replace the customer references, date and fund selection before sending a request. Collect all declarations from the holder; the example answers are not defaults.

```json
{
  "input": {
    "prosperityJunior": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-holder@example.com"
              }
            }
          }
        },
        {
          "role": [
            "INSURED_PERSON"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-child@example.com"
              }
            }
          }
        }
      ],
      "customerFinancialStatus": {
        "hasSwissIncome": true,
        "moneyOrigin": "EARNED_INCOME",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 300000,
        "totalMonthlyNetIncome": 600000,
        "differentWealthOrigin": false
      },
      "policyHolderHealthStatus": {
        "worksAsSelfEmployed": false,
        "employmentWorkload": 100,
        "height": 180,
        "weight": 75,
        "existingInsuranceContract": {
          "hasExistingInsuranceContract": false
        },
        "hasAggravatedTermsContract": false,
        "additionalHealthRisk": {
          "hasAdditionalRisks": false
        },
        "knownDiseases": {
          "hasHadKnownDiseases": false
        },
        "hasExistingDisabilities": false,
        "medication": {
          "hasBeenRegularlyMedicated": false
        },
        "hospitalization": {
          "hasBeenHospitalized": false
        },
        "hasAnnuity": false,
        "drugAbuse": {
          "hasBeenTreatedForDrugAbuse": false
        },
        "smoking": {
          "hasSmoked": false
        },
        "hasHIV": false,
        "medicalPractitionerInformation": "Synthetic practitioner, Teststrasse 2, 8001 Zürich"
      },
      "productConfiguration": {
        "startDate": "2026-11-01",
        "ageWhenPolicyEnds": 66,
        "regularPremium": 20000,
        "premiumMode": "MONTHLY",
        "additionalPayment": 100000,
        "guarantee": "SELECT50",
        "maturityManagement": true,
        "language": "DE_CH",
        "investmentStrategy": {
          "riskLevel": "HIGH",
          "fundSelection": [
            {
              "id": "LU0070176184",
              "percentage": 100
            }
          ],
          "goals": {
            "longTerm": true,
            "taxBenefit": false,
            "flexibility": true
          },
          "lowRiskInvestment": false,
          "rebalancingType": "NONE",
          "sustainabilityDetails": {
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE",
            "percentage": 0,
            "topicsToInclude": [],
            "topicsToExclude": []
          }
        }
      }
    }
  }
}
```

**Note:**
- Holder entry age: 18–75; child entry age: 0–15; policy end by holder age 85.
- Minimum policy/payment terms: ten/five years. Annual premiums must be at least CHF 1,200, with an agreed regular-premium sum of at least CHF 12,000.
- `additionalPayment` is 0 or at least CHF 500. Regular premiums are amounts per payment, in CHF minor units.
- Retrieve funds with `availableFunds(product: PROSPERITY_JUNIOR)`. Select50/80 require twenty policy/payment years; Select100 requires thirty. Any guarantee requires `maturityManagement: true`.
- Optional holder premium waiver requires entry age at most 60 and a waiting period of 6, 12 or 24 months. Relative disability annuities and guardian signing are outside this creation support.
- Follow the [shared Swiss requirements](#swiss-savings-requirements), including the environment-specific health questions and consultation protocol.

</details>

<details id="example-liechtenstein-life-wealth-ch">
<summary>Example: Liechtenstein Life Wealth CH (Swiss Pillar 3b)</summary>

Use `liechtensteinLifeWealthCH` with one individual carrying all five roles: `POLICY_HOLDER`, `INSURED_PERSON`, `PAYER`, `MAILING` and `ECONOMIC_INTEREST`. The holder supplies the financial and detailed health declarations. Choose exactly one premium variant and one death-cover variant.

These examples reference a synthetic holder born in 1985. Replace the customer reference, date and fund selection before sending a request. Collect every declaration from the customer; the example answers are not defaults.

#### Single premium

This example invests CHF 50,000 and selects fiscal minimum death cover.

```json
{
  "input": {
    "liechtensteinLifeWealthCH": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST",
            "INSURED_PERSON"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-holder@example.com"
              }
            }
          }
        }
      ],
      "customerFinancialStatus": {
        "hasSwissIncome": true,
        "moneyOrigin": "EARNED_INCOME",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 300000,
        "totalMonthlyNetIncome": 600000,
        "differentWealthOrigin": false
      },
      "policyHolderHealthStatus": {
        "worksAsSelfEmployed": false,
        "employmentWorkload": 100,
        "height": 180,
        "weight": 75,
        "existingInsuranceContract": {
          "hasExistingInsuranceContract": false
        },
        "hasAggravatedTermsContract": false,
        "additionalHealthRisk": {
          "hasAdditionalRisks": false
        },
        "knownDiseases": {
          "hasHadKnownDiseases": false
        },
        "hasExistingDisabilities": false,
        "medication": {
          "hasBeenRegularlyMedicated": false
        },
        "hospitalization": {
          "hasBeenHospitalized": false
        },
        "hasAnnuity": false,
        "drugAbuse": {
          "hasBeenTreatedForDrugAbuse": false
        },
        "smoking": {
          "hasSmoked": false
        },
        "hasHIV": false,
        "medicalPractitionerInformation": "Synthetic practitioner, Teststrasse 2, 8001 Zürich"
      },
      "productConfiguration": {
        "startDate": "2026-11-01",
        "ageWhenPolicyEnds": 66,
        "premium": {
          "singlePremium": 5000000
        },
        "coverage": {
          "minimalTax": true
        },
        "guarantee": "SELECT50",
        "maturityManagement": true,
        "language": "DE_CH",
        "investmentStrategy": {
          "riskLevel": "HIGH",
          "fundSelection": [
            {
              "id": "IE00B8J37J31",
              "percentage": 100
            }
          ],
          "goals": {
            "longTerm": true,
            "taxBenefit": false,
            "flexibility": true
          },
          "lowRiskInvestment": false,
          "rebalancingType": "NONE",
          "sustainabilityDetails": {
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE",
            "percentage": 0,
            "topicsToInclude": [],
            "topicsToExclude": []
          }
        }
      }
    }
  }
}
```

#### Regular premiums

This example pays CHF 200 each month and CHF 1,000 initially. `regularPremium` is the amount per payment, not an annual amount.

```json
{
  "input": {
    "liechtensteinLifeWealthCH": {
      "associatedPersons": [
        {
          "role": [
            "POLICY_HOLDER",
            "PAYER",
            "MAILING",
            "ECONOMIC_INTEREST",
            "INSURED_PERSON"
          ],
          "person": {
            "existingCustomer": {
              "byEmail": {
                "email": "swiss-holder@example.com"
              }
            }
          }
        }
      ],
      "customerFinancialStatus": {
        "hasSwissIncome": true,
        "moneyOrigin": "EARNED_INCOME",
        "policyReason": "PRIVATE_PENSION",
        "totalMonthlyExpenses": 300000,
        "totalMonthlyNetIncome": 600000,
        "differentWealthOrigin": false
      },
      "policyHolderHealthStatus": {
        "worksAsSelfEmployed": false,
        "employmentWorkload": 100,
        "height": 180,
        "weight": 75,
        "existingInsuranceContract": {
          "hasExistingInsuranceContract": false
        },
        "hasAggravatedTermsContract": false,
        "additionalHealthRisk": {
          "hasAdditionalRisks": false
        },
        "knownDiseases": {
          "hasHadKnownDiseases": false
        },
        "hasExistingDisabilities": false,
        "medication": {
          "hasBeenRegularlyMedicated": false
        },
        "hospitalization": {
          "hasBeenHospitalized": false
        },
        "hasAnnuity": false,
        "drugAbuse": {
          "hasBeenTreatedForDrugAbuse": false
        },
        "smoking": {
          "hasSmoked": false
        },
        "hasHIV": false,
        "medicalPractitionerInformation": "Synthetic practitioner, Teststrasse 2, 8001 Zürich"
      },
      "productConfiguration": {
        "startDate": "2026-11-01",
        "ageWhenPolicyEnds": 66,
        "premium": {
          "regularPremium": {
            "regularPremium": 20000,
            "premiumMode": "MONTHLY",
            "additionalPayment": 100000
          }
        },
        "coverage": {
          "minimalTax": true
        },
        "guarantee": "SELECT50",
        "maturityManagement": true,
        "language": "DE_CH",
        "investmentStrategy": {
          "riskLevel": "HIGH",
          "fundSelection": [
            {
              "id": "IE00B8J37J31",
              "percentage": 100
            }
          ],
          "goals": {
            "longTerm": true,
            "taxBenefit": false,
            "flexibility": true
          },
          "lowRiskInvestment": false,
          "rebalancingType": "NONE",
          "sustainabilityDetails": {
            "customerKnowledgeStatus": "WAIVED_CONSULTATION_DUE_TO_PRE_EXISTING_KNOWLEDGE",
            "percentage": 0,
            "topicsToInclude": [],
            "topicsToExclude": []
          }
        }
      }
    }
  }
}
```

**Note:**
- Single premium: at least CHF 20,000; holder entry age 18–65; policy end age 60–100; minimum policy term ten years, including guarantees.
- Regular premiums: holder entry age 18–75; policy end age 60–85; minimum policy/payment terms ten/five years; at least CHF 2,000 annually and CHF 10,000 in agreed regular premiums. Initial top-up is 0 or at least CHF 1,000.
- Regular-premium Select50/80 require twenty policy years; Select100 requires thirty. Every regular-premium guarantee requires at least twenty payment years. Any guarantee requires `maturityManagement: true`.
- `premium` accepts exactly one of `singlePremium` or `regularPremium`. All amounts use CHF minor units.
- `coverage` accepts `minimalTax: true` or a positive `chosenAmount`. Chosen cover cannot exceed 200% of the applicable premium sum; Lifeware also validates its calculated minimum.
- Retrieve funds with `availableFunds(product: LIECHTENSTEIN_LIFE_WEALTH_CH)`. No premium-waiver input is exposed.
- Follow the [shared Swiss requirements](#swiss-savings-requirements), including the environment-specific health questions and consultation protocol.

</details>

### Swiss savings requirements

The Duo, Junior and Wealth CH branches require an explicit product grant for the acting partner. Existing access to another Swiss product does not grant access automatically. These branches support the listed tariffs only; companies, cross-border tariffs and other tariff years are not exposed.

Each individual can use the normal `newCustomer` or `existingCustomer` selector. Existing individuals must be linked to the acting broker and have a stored date of birth. For Duo and Junior, that requirement applies to both the holder and the relative. The holder needs an email address and tax-residency information. Do not give different individuals the same email address.

Collect every investment, financial and health answer from the customer. `customerFinancialStatus.hasSwissIncome` is required and records whether the holder has income in Switzerland. Supply the actual answer, including `false` for a holder without Swiss income; residence, nationality and CHF premiums do not establish it. Synthetic negative answers in examples are not defaults to fill on a customer's behalf.

All amounts are integer CHF minor units (Rappen): `20000` is CHF 200 and `100000` is CHF 1,000. `regularPremium` is the amount **per payment**. With `MONTHLY`, `20000` means CHF 200 twelve times a year; with `ANNUALLY`, it means only CHF 200 per year.

`lowRiskInvestment` is required. Supply the customer's actual declaration, including an explicit `false` when appropriate. Start dates can be daily, from today through three calendar months ahead. Backdating is unavailable. Premiums settle by bank transfer/standing order. Omitted document language defaults to `DE_CH`; `DE_DE`, `FR_FR` and `IT_IT` are also available.

#### Swiss consultation protocol

The application includes the consultation protocol even when `consultation` is omitted. The legacy `disableConsultationWaiver` input currently cannot remove those pages: the API always sends `external_advice_protocol: false`. A licensed broker can supply `consultation` to prefill the advice and confirmations. Omitting it leaves the protocol for completion rather than removing it.

#### Retrieve Swiss product funds

Use the product-specific fund catalogue before building the investment selection. Select free investment funds; the insurance system adds the applicable guarantee fund when a guarantee is selected.

```graphql
query SwissSavingsFunds($product: PlatformInsuranceProduct!) {
  availableFunds(product: $product, pagination: { first: 100 }) {
    __typename
    ... on AvailableFundsConnection {
      edges {
        node {
          isin
          name
          isGuaranteeFund
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

Use `PROSPERITY_DUO`, `PROSPERITY_JUNIOR` or `LIECHTENSTEIN_LIFE_WEALTH_CH` for `$product`. Continue pagination when `hasNextPage` is true. Pass the selected `isin` as `fundSelection[].id`; percentages must sum to 100, with no duplicate funds and at most ten funds.

#### Swiss health questions by environment

The new Swiss branches follow the same temporary production split as Value Invest VWL for
smoking and physician details. All other detailed health declarations remain required.

| Declaration | Staging (`test2`) and Stable (`test`) | Production |
|---|---|---|
| Disease, medication and other detailed answers | Required and sent using the Swiss questionnaire keys | Required and sent using the same Swiss keys |
| `smoking` | Required and sent | Optional; validated for consistency when supplied, then omitted from the Lifeware request |
| `medicalPractitionerInformation` | Required and nonblank; sent as `medic` | Optional; omitted from the Lifeware request |

Both fields are nullable in the GraphQL schema because production permits their omission.
Staging and Stable validate the requirements during offer creation. An integration can send the
complete example payload in every environment; production currently leaves smoking and
physician details out of its provider request. Never invent a missing health answer.

Staging application PDFs verify the Swiss detailed mapping. Stable follows the non-production
mapping but has not been tested against Lifeware. The production split is a provisional mapping
based on the documented VWL rollout; **production behavior for these Swiss tariffs still needs
manual verification**. Do not replace the Swiss disease fields with VWL's combined-question
fields or apply its proposed EUR 35,000 threshold to CHF products.

#### Swiss age, premium and term rules

| Rule | Duo | Junior | Wealth CH: single | Wealth CH: regular |
|---|---|---|---|---|
| Holder entry age | 18–75 | 18–75 | 18–65 | 18–75 |
| Relative entry age | 16–60 | 0–15 | Holder is insured | Holder is insured |
| Holder end age | At most 85 | At most 85 | 60–100 | 60–85 |
| Minimum policy term | 10 years | 10 years | 10 years | 10 years |
| Minimum payment term | 5 years | 5 years | Single payment | 5 years |
| Minimum regular premium per year | CHF 1,200 | CHF 1,200 | Not applicable | CHF 2,000 |
| Minimum agreed regular-premium sum | CHF 12,000 | CHF 12,000 | Not applicable | CHF 10,000 |
| Initial top-up | 0 or at least CHF 500 | 0 or at least CHF 500 | Premium at least CHF 20,000 | 0 or at least CHF 1,000 |

For regular premiums, omit `ageUntilPremiumIsPaid` to pay until policy end. When present, it is the **holder's** age when payments end. The payment term must not exceed the policy term.

Start dates can be daily, from today through three calendar months ahead. Backdating is unavailable. Premiums settle by bank transfer/standing order; these branches expose no alternate payment-method input. Omitted document language defaults to `DE_CH`; `DE_DE`, `FR_FR` and `IT_IT` are also available.

##### Guarantees and maturity management

Use `NO_GUARANTEE`, `SELECT50`, `SELECT80` or `SELECT100`. Omit `guarantee` for no guarantee. Any selected guarantee requires `maturityManagement: true`.

| Variant | Select50/Select80 minimum policy term | Select100 minimum policy term | Minimum payment term with a guarantee |
|---|---|---|---|
| Duo and Junior | 20 years | 30 years | 20 years for Select50/80; 30 years for Select100 |
| Wealth CH: regular | 20 years | 30 years | 20 years for every guarantee level |
| Wealth CH: single | 10 years | 10 years | Single payment |

For Duo and Junior, optional `premiumWaiver` covers the holder's occupational disability, with a waiting period of 6, 12 or 24 months. Holder entry age must not exceed 60. The policy can continue beyond the waiver coverage period under the product terms. Wealth CH exposes no premium-waiver input.

#### Swiss detailed health declarations

`policyHolderHealthStatus` is required for all three branches. For Duo and Junior, the policyholder is the insured provider. The relative's separate `INSURED_PERSON` role does not make that relative the subject of this health declaration.

Use the detailed grouped fields shown above. A positive grouped answer requires its details; a negative answer must omit details. For example:

```json
{
  "knownDiseases": {
    "hasHadKnownDiseases": true,
    "diseaseDetails": "Synthetic example: condition, period, recovery and treating practitioner"
  },
  "smoking": {
    "hasSmoked": true,
    "smokingDetails": "Synthetic example: substance and daily quantity"
  }
}
```

The same consistency rule applies to existing insurance, additional health risks, medication, hospitalization and drug-abuse disclosures. Drug-abuse disclosures require both treatment and substance details. Provide the actual physician/practitioner information, body measurements and workload. Do not use the German VWL `hasCriticalIllness` fields or a simplified questionnaire as a substitute for these detailed Swiss declarations.

Disability annuities for the relative are not exposed by these creation branches. Relative health mapping remains unresolved. Junior's in-app guardian signing journey is also outside this creation support.

#### Swiss results, errors and documents

Handle `__typename`, every `ErrorInterface` result, and top-level GraphQL errors. Examples of validation outcomes include `PRODUCT_CONFIGURATION_SWISS_SAVINGS`, `HEALTH_STATE_SWISS_SAVINGS`, person-role errors and fund-selection errors. A partner without the product grant receives `UnauthorizedOperationError`.

A successful `CreatedOffer.contractID` identifies the offer. Follow the existing [document retrieval flow](https://partner.life.li/integration-docs/platform-integrations/creating-offers#option-1-download-application-document) to obtain its application form after synchronization. Inspect the generated application when verifying an integration, including positive health answers and the persons named on the form.

Creation does not establish signing readiness, underwriting acceptance, submission or policy issuance. The separate relative-health and guardian requirements must be resolved before relying on an end-to-end Duo/Junior application journey. Cross-border tariffs and other tariff years are not exposed by these branches.

These creation checks use staging (`test2`). Stable and production behavior require separate verification; a staging result does not establish parity.

### Fetching the PDF Document

**Note:**
Wait ~30 seconds after offer creation before requesting documents to avoid `offer not found` errors.

```graphql
query Offer($contractId: PolicyID!) {
  offer(contractID: $contractId) {
    ... on ErrorInterface {
      __typename
      message
    }
    ... on Offer {
      contractID
      applicationFormDownloadLink {
        ... on FileDownload {
          link
        }
      }
    }
  }
}
```

### Value Invest VWL: who sets the standing order up

VWL premiums are paid by the **employer**, never by the employee, so arranging the payment happens outside the offer. `customerFinancialStatus.paymentMethod: { "wireTransfer": ... }` says who does the arranging, and on VWL both answers are open to you:

| Value            | What Liechtenstein Life does                                   | What you have to do                                                 |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------------------- |
| `true` (default) | Nothing. The employer is expected to arrange the transfer alone. | Forward the standing-order page to the employer yourself — see below. |
| `false`          | Notifies the employer to set the standing order up.              | Nothing.                                                              |

Omitting the value is the same as `true`.

**`false` is accepted on Value Invest VWL only.** Every other product returns `InputValidationError` with `invalidInput: FINANCIAL_STATE_WIRE_TRANSFER_FALSE_NOT_SUPPORTED`, because there the payer is the person signing the offer and there is nobody else to notify.

#### Forwarding the standing-order page

This applies when you send `true`, or send nothing. The application document fetched above contains a page written for exactly this purpose:

> **VWL Antrag auf Überweisung vermögenswirksamer Leistungen durch den Arbeitgeber**

**Forward that page to the employer.** Nothing else in the flow does it — the employee signs the application form, but the employer only learns the amount, the account and the reference from this page. Forward it per offer, not per employer: the contribution amount and the `personalNumber` differ for every employee.

Skipping this step stalls the policy: the contributions never arrive and nobody is told to send them. If you would rather Liechtenstein Life contacted the employer, send `false`.

### Uploading Required Documents

Once the customer has signed the application form, upload it back along with an identity document using the `uploadDocument` mutation. Both documents are typically required by the insurance system before issuance. If either is missing, `submitOffer` will return `SubmitOfferValidationError` listing the specific issues from the insurance system.

```graphql
mutation UploadDocument($input: UploadDocumentInput!) {
  uploadDocument(input: $input) {
    __typename
    ... on DocumentUploaded {
      contractID
      documentId
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

**Input fields:**

- `contractID` — the `Contract ID` returned by `createOffer`
- `file` — a multipart `Upload` (see note below)
- `documentType` — one of:
  - `SIGNED_APPLICATION_FORM` — the application form signed by both the customer and the broker
  - `IDENTITY_VERIFICATION` — an identity document (passport, ID card, etc.) for the customer. It is the partner's responsibility to ensure the document is legitimate and belongs to the customer.

**File requirements:**

- Formats: `pdf`, `doc`, `docx`
- Maximum size: **5 MB**
- Files that exceed the limit or have an unsupported format return `InvalidDocumentFormatError`

**Note:**
The `file` argument uses the [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec). Send the request as `multipart/form-data` with an `operations` field containing the GraphQL payload, a `map` field binding the file variable, and the file itself. The request must also carry an `apollo-require-preflight: true` header — Apollo Server's CSRF prevention blocks multipart requests without it and returns a `BAD_REQUEST` error otherwise.

```bash
curl https://api.stable.life.li/graphql/partner-platform \
  -H "Authorization: Bearer YOUR-API-KEY" \
  -H "x-partner-id: YOUR-PARTNER-ID" \
  -H "apollo-require-preflight: true" \
  -F operations='{ "query": "mutation ($input: UploadDocumentInput!) { uploadDocument(input: $input) { __typename ... on DocumentUploaded { documentId } ... on ErrorInterface { message } } }", "variables": { "input": { "contractID": "YOUR-CONTRACT-ID", "file": null, "documentType": "SIGNED_APPLICATION_FORM" } } }' \
  -F map='{ "0": ["variables.input.file"] }' \
  -F 0=@./signed-application.pdf
```

The example above uses POSIX shell quoting and works in bash, zsh, and PowerShell. On Windows `cmd.exe`, use PowerShell or WSL, or use a GraphQL client library (Apollo, urql) instead.

Most GraphQL clients (Apollo, urql, graphql-request) have first-class support for `Upload` via plugins such as `apollo-upload-client`.

**Possible responses:**

| Type                         | When                                                               |
| ---------------------------- | ------------------------------------------------------------------ |
| `DocumentUploaded`           | Upload succeeded; `documentId` identifies the file                 |
| `OfferNotFoundError`         | No offer exists for `contractID` under your partner account        |
| `InvalidDocumentFormatError` | Unsupported file type, or file exceeds the 5 MB limit              |
| `UnexpectedError`            | System failure — retry once. If the error persists, contact support. |

### Submitting the Offer

Once you have uploaded the documents needed by the insurance system, submit the offer for issuance with the `submitOffer` mutation. Submission is **protected against duplicates**: a second call for the same `contractID` returns `OfferAlreadySubmittedError`, which indicates the offer is already in the submission pipeline — no further action is required. This makes `submitOffer` safe to retry after a network timeout: if the first call actually reached the server, the retry will report `OfferAlreadySubmittedError` rather than re-submitting.

```graphql
mutation SubmitOffer($input: SubmitOfferInput!) {
  submitOffer(input: $input) {
    __typename
    ... on SubmittedOffer {
      contractID
    }
    ... on SubmitOfferValidationError {
      message
      validationErrors {
        title
        description
      }
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

**Possible responses:**

| Type                          | When                                                                                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SubmittedOffer`              | Offer was accepted by the insurance system and enters the issuance workflow                                                                               |
| `OfferNotFoundError`          | No offer exists for `contractID` under your partner account                                                                                               |
| `OfferAlreadySubmittedError`  | Offer was already submitted (or a submission is in progress) — no action needed                                                                           |
| `SubmitOfferValidationError`  | Insurance system rejected the offer with validation errors listed in `validationErrors`. Fix the flagged data (or re-upload documents) and retry.         |
| `UnexpectedError`             | System failure — retry once. If the error persists, contact support.                                                                                      |

**Note:**
When `SubmitOfferValidationError` is returned, the offer's submission state is rolled back internally so you can fix the data and call `submitOffer` again. No manual reset step is required.

### Checking Offer Status

Use the `offerStatus` query to check the lifecycle state of an offer and whether it has any open reworks. This is a lightweight read and can be polled after `submitOffer` to track progress without fetching the full offer.

```graphql
query OfferStatus($contractID: PolicyID!) {
  offerStatus(contractID: $contractID) {
    __typename
    ... on OfferStatus {
      contractID
      status
      isSubmitted
      isIssued
      hasOpenReworks
      openReworks {
        taskId
        openedOn
        reason
        status
      }
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

**Lifecycle states (`status`):**

| Value       | Meaning                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------- |
| `OFFER`     | Offer created, not yet submitted                                                         |
| `SUBMITTED` | Offer sent to the insurance system, processing in progress                               |
| `ISSUED`    | Offer has been converted into an active policy                                           |
| `CANCELLED` | Offer has been cancelled (terminal — overrides `ISSUED` if cancelled after issuance)     |

### Responding to Open Reworks

If the insurance system needs additional information or corrections, it opens a **rework** against the offer. Unlike the `openReworks` field inside `offerStatus` (which returns reworks for a single offer), the `openReworks` query returns all open reworks across every offer under your partner account — useful for building a rework dashboard. Use it to list all open reworks:

```graphql
query OpenReworks {
  openReworks {
    __typename
    ... on OpenReworks {
      totalCount
      reworks {
        taskId
        contractID
        openedOn
        reason
        status
      }
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

Only reworks with status `WAITING` (awaiting a response from the broker) are returned. After you address the flagged items (typically by re-uploading a corrected document with `uploadDocument`), the rework automatically transitions from `WAITING` to `FROZEN` (broker responded, internal confirmation pending). The transition to `FINISHED` is completed by the insurance system and may take additional processing time.

### Updating Customer Information

You can update existing customer information through the API if:

- They are linked to your partner account
- The information is allowed to be updated (some fields are restricted once contracts exist)

```graphql
mutation UpdateCustomer(
  $customerBy: CustomerByInput!
  $input: UpdateCustomerInput!
) {
  updateCustomer(customerBy: $customerBy, input: $input) {
    ... on ErrorInterface {
      message
    }
    ... on InsuranceSystemError {
      message
      reasons
    }
    ... on UpdatedCustomer {
      customer {
        ... on IndividualPersonCustomer {
          ID
        }
      }
    }
  }
}
```

**Note:**
First name, last name, gender and date of birth can only be changed while the customer is related to offers alone — no application, no broker relation and no contract. A request that includes one of them for any other customer is rejected in full, so the permitted fields in that same request are not applied either. Resend those on their own, and contact Liechtenstein Life Assurance AG customer service to correct a locked field.

### Looking Up Customer ID

You can retrieve a customer's ID using their email address:

```graphql
query Customer($input: CustomerByInput!) {
  customer(input: $input) {
    __typename
    ... on ErrorInterface {
      message
    }
    ... on IndividualPersonCustomer {
      ID
    }
    ... on CorporateEntityCustomer {
      ID
    }
  }
}
```

### Registering a Customer

If your flow creates the customer before the offer — or without one — `createCustomer` registers them in the insurance system, assigned to the broker in your `x-partner-id` header, and returns their ID in the same call.

```graphql
mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    __typename
    ... on CreatedCustomer {
      customerID
    }
    ... on ErrorInterface {
      message
    }
    ... on InsuranceSystemError {
      reasons
    }
    ... on InputValidationError {
      invalidInput
    }
  }
}
```

```json
{
  "input": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "dateOfBirth": "1990-05-17",
    "gender": "FEMALE",
    "maritalStatus": "MARRIED",
    "nationality": "CH",
    "email": "ada.lovelace@example.com",
    "profession": "Analyst",
    "mobilePhone": "+41791234567",
    "address": {
      "street": "Bahnhofstrasse",
      "houseNumber": "1",
      "zip": "9490",
      "city": "Vaduz",
      "country": "LI"
    }
  }
}
```

**Response**

```json
{
  "data": {
    "createCustomer": {
      "__typename": "CreatedCustomer",
      "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc"
    }
  }
}
```

Pass the returned `customerID` as `existingCustomer.byID.ID` when you create the offer.

## Error Handling

The API uses a schema-based error handling approach:

- All errors implement `ErrorInterface`
- Errors are self-documenting
- Never query error types directly
- Access errors through `ErrorInterface` to avoid breaking changes

Common error responses:

```json
{
  "data": {
    "createOffer": {
      "__typename": "InsuranceSystemError",
      "message": "Offer can not be created due to some insurance system errors",
      "reasons": [
        "Negative projection: The model cannot be computed. The basic data must be changed",
        "Premium: Application limits regular premium (yearly): EUR 1,200.00 - EUR 1,000,000.00"
      ]
    }
  }
}
```

Learn more about our [error handling pattern](https://sachee.medium.com/200-ok-error-handling-in-graphql-7ec869aec9bc).

---

## Available Funds

URL: https://partner.life.li/integration-docs/platform-integrations/funds

# Available Funds

`createOffer` rejects any fund your offer selects that isn't in the product's range — today, that means finding out only when the insurance system turns down the offer. The `availableFunds` query answers the question upfront: it returns exactly the funds a product's default tariff accepts, so you can validate a customer's fund selection before you ever call `createOffer`.

Pass a fund's `isin` from the result as `FundSelectionInput.id` — the same field `investmentStrategy.fundSelection` takes on [`createOffer`](https://partner.life.li/integration-docs/platform-integrations/creating-offers).

## Fetching the fund range

Pass the product you want the range for. Omit `pagination` to get the first 50 funds.

```graphql
query AvailableFunds($product: PlatformInsuranceProduct!, $pagination: FundsPaginationInput) {
  availableFunds(product: $product, pagination: $pagination) {
    __typename
    ... on AvailableFundsConnection {
      totalCount
      syncedAt
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      edges {
        cursor
        node {
          isin
          name
          riskLevel
          isSustainable
          isGuaranteeFund
        }
      }
    }
    ... on UnauthorizedOperationError {
      message
    }
    ... on InputValidationError {
      invalidInput
      message
    }
    ... on UnexpectedError {
      message
    }
  }
}
```

```json
{
  "product": "PROSPERITY_3A"
}
```

**Response**

```json
{
  "data": {
    "availableFunds": {
      "__typename": "AvailableFundsConnection",
      "totalCount": 2,
      "syncedAt": "2026-08-16T21:00:00.000Z",
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": "3f9b6a2e-1d4c-4b8a-9e21-7c5d0a4f6b12",
        "endCursor": "8a21c4f0-6b7d-4e9a-b312-5d0f6a4c8b19"
      },
      "edges": [
        {
          "cursor": "3f9b6a2e-1d4c-4b8a-9e21-7c5d0a4f6b12",
          "node": {
            "isin": "LLA030",
            "name": "Prosperity Guarantee Fund",
            "riskLevel": 2,
            "isSustainable": false,
            "isGuaranteeFund": true
          }
        },
        {
          "cursor": "8a21c4f0-6b7d-4e9a-b312-5d0f6a4c8b19",
          "node": {
            "isin": "LU0070176184",
            "name": "Global Equities Index Fund",
            "riskLevel": 5,
            "isSustainable": true,
            "isGuaranteeFund": false
          }
        }
      ]
    }
  }
}
```

## Fund risk

Each fund carries the insurance system's own risk classification, `riskLevel`, from 1 (lowest) to 7 (highest). `null` means the fund carries no risk profile.

**Note:**
This is the fund's risk, not a customer's — we publish no rule mapping one to the other. Selecting funds above what a customer's profile allows is validated by the insurance system before issuance, not by this API. `availableFunds` tells you a fund is in the product's range, not that a given customer may select it.

Full field-by-field reference: [Schema Reference](https://partner.life.li/integration-docs/docs/schema).

---

## Platform GraphQL API

URL: https://partner.life.li/integration-docs/platform-integrations/graphql-api

# Platform GraphQL API

The Platform GraphQL API provides advanced capabilities for creating and managing complete offers. Access the API at:

- Test Environment: [https://api.stable.life.li/graphql/partner-platform](https://api.stable.life.li/graphql/partner-platform)
- Production: [https://api.life.li/graphql/partner-platform](https://api.life.li/graphql/partner-platform)

## Authentication

Both endpoints include a GraphQL playground for interactive API exploration. To authenticate:

1. In the browser authentication popup:

   - Leave the username empty
   - Enter your API key as the password

2. In the playground's Headers section, add:
   ```json
   {
     "Authorization": "Bearer YOUR-API-KEY",
     "x-partner-id": "YOUR-PARTNER-ID"
   }
   ```

**Note:**
If you're working with multiple partner IDs or are a platform serving multiple partners:

- Each Partner ID must be mapped to your API key
- Contact support to set up new ID mappings
  :::

## Environments

- **Stable**: A clone of our production environment, ideal for development and testing
- **Production**: Live environment for real transactions

**Note:**
If you previously used the Customer Digital Onboarding flow and the `partner` graph, your existing credentials will work with the `partner-platform` graph.

See [Migrating from Digital Onboarding](https://partner.life.li/integration-docs/platform-integrations/migrating-from-digital-onboarding) for the field mappings and new required fields for Liechtenstein Life Invest.

## Security Best Practices

1. Keep your API key secure and never expose it in client-side code
2. Use environment variables for storing credentials
3. Request new API keys if they are compromised
4. Use HTTPS for all API communications

## AI Integration Prompt

Copy this prompt and paste it into your AI coding assistant to set up the API client:

## Interactive API Explorer

Explore the schema and run queries directly in the GraphQL playground:

- **Test**: [api.stable.life.li/graphql/partner-platform](https://api.stable.life.li/graphql/partner-platform)
- **Production**: [api.life.li/graphql/partner-platform](https://api.life.li/graphql/partner-platform)

Authenticate via the browser Basic Auth popup (leave username empty, enter your API key as password), then add your headers in the playground's Headers tab.

---

## Platform Integration

URL: https://partner.life.li/integration-docs/platform-integrations

# Platform Integration

For partners with existing platforms or CRM systems containing complete customer and policy information, our Platform Integration lets you create binding offers and prepare Altersvorsorgedepot Plus pre-registrations through our API. This integration enables you to:

- Create complete offers with all required fields
- Create Altersvorsorgedepot Plus pre-registrations and send customer invitations
- List the Altersvorsorgedepot pre-registrations and invitations your Vermittler have added, and get notified of new ones
- Download offer documents
- Upload signed application forms and identity documents
- Submit offers for issuance to the insurance system
- Track offer status and respond to open reworks
- Access offers through Partner Life
- Read the policies connected to your account and the fund units they currently hold
- Manage the entire process through API integration

## Integration Steps

1. [Getting Started with GraphQL API](https://partner.life.li/integration-docs/platform-integrations/graphql-api)
   - Already use Digital Onboarding? [Migrate your existing integration](https://partner.life.li/integration-docs/platform-integrations/migrating-from-digital-onboarding).
2. [Partner Life Single Sign-On](https://partner.life.li/integration-docs/platform-integrations/single-sign-on)
3. [Creating Complete Offers](https://partner.life.li/integration-docs/platform-integrations/creating-offers)
4. [Creating and Listing Pre-Registrations](https://partner.life.li/integration-docs/platform-integrations/pre-registrations)
5. [Webhooks](https://partner.life.li/integration-docs/platform-integrations/webhooks)

## Other Endpoints

Beyond creating offers, the Platform GraphQL API exposes further data about your book:

- [Policies](https://partner.life.li/integration-docs/platform-integrations/policies) — the policies connected to your account and the fund units they currently hold
- [Available Funds](https://partner.life.li/integration-docs/platform-integrations/funds) — the funds a product accepts, so you can validate a customer's fund selection before calling `createOffer`
- [Quick Offers](https://partner.life.li/integration-docs/platform-integrations/quick-offers) — projected values and a sample-offer PDF from a date of birth and a premium, before you collect any customer data

## Supported Products

| Product | Market | Offering Details | API Integration |
|---------|--------|-----------------|-----------------|
| **Liechtenstein Life Invest** | Germany 🇩🇪 | [View Details](https://liechtensteinlife.com/en-DE/markets/de/products/liechtenstein-life-invest) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-liechtenstein-life-invest) |
| **Liechtenstein Life Wealth** | Germany 🇩🇪 | [View Details](https://liechtensteinlife.com/en-DE/markets/de/products/liechtenstein-life-wealth) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-liechtenstein-life-wealth) |
| **Prosperity Plus Germany** | Germany 🇩🇪 | [View Details](https://liechtensteinlife.com/en-DE/markets/de/products/prosperity-plus) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-prosperity-plus-germany) |
| **Liechtenstein Life Pension** | Germany 🇩🇪 | [View Details](https://liechtensteinlife.com/en-DE/markets/de/products/liechtenstein-life-pension) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-liechtenstein-life-pension) |
| **Value Invest VWL** | Germany 🇩🇪 | [View Details](https://liechtensteinlife.com/en-DE/markets/de/products/value-invest-vwl) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-value-invest-vwl) |
| ~~**Yourlife Netto Plus**~~ _(deprecated — no new integrations)_ | Germany 🇩🇪 | — | — |
| **Prosperity 3A** | Switzerland 🇨🇭 | [View Details](https://liechtensteinlife.com/en-CH/markets/ch/products/prosperity-3a) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-prosperity-3a-swiss-pillar-3a) |
| **Prosperity Plus (3B)** | Switzerland 🇨🇭 | [View Details](https://liechtensteinlife.com/en-CH/markets/ch/products/prosperity-3b) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-prosperity-plus-swiss-pillar-3b) |
| **Prosperity Duo** | Switzerland 🇨🇭 | [View Details](https://liechtensteinlife.com/en-CH/markets/ch/products/prosperity-duo) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-prosperity-duo) |
| **Prosperity Junior** | Switzerland 🇨🇭 | [View Details](https://liechtensteinlife.com/en-CH/markets/ch/products/prosperity-junior) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-prosperity-junior) |
| **Liechtenstein Life Wealth CH** | Switzerland 🇨🇭 | [View Details](https://liechtensteinlife.com/en-CH/markets/ch/products/liechtenstein-life-wealth) | [View Example](https://partner.life.li/integration-docs/platform-integrations/creating-offers#example-liechtenstein-life-wealth-ch) |

## Need Help?

If you need assistance with the integration or have questions about supported products, please reach out to our support team.

---

## Prosperity 3A — Job Classes & Risk Levels

URL: https://partner.life.li/integration-docs/platform-integrations/job-classes

# Prosperity 3A — Job Classes & Risk Levels

When configuring `disabilityAnnuity` for a Prosperity 3A offer, you must provide a valid `jobClass` and `jobRisk` pair.
The `jobClass` string must match exactly (case-sensitive), and the `jobRisk` must be a valid risk level for that job class.

Some job classes have multiple valid risk levels (e.g., "Professional Footballer" has risk levels 1–5).

Use the search box below to find valid job classes.

<JobClassTable />

## Usage in GraphQL

```graphql
"disabilityAnnuity": {
  "yearlyPensionAmount": 600000,
  "excludeAccident": false,
  "annuityIncrease": true,
  "waitingPeriodMonths": 24,
  "jobClass": "Pharmacist",
  "jobRisk": 1
}
```

## Notes

- The `jobClass` value is **case-sensitive** and must match the table exactly
- If an invalid `jobClass` or `jobRisk` is provided, the API returns `PRODUCT_CONFIGURATION_INVALID_JOB_CLASS`
- Risk levels range from 1 (lowest risk) to 5 (highest risk)
- 29 job classes have multiple valid risk levels — check the table for the correct one

---

## Migrating from Digital Onboarding

URL: https://partner.life.li/integration-docs/platform-integrations/migrating-from-digital-onboarding

---
description: "Move your Liechtenstein Life Invest integration to the Platform API: field mappings, required additions, and customer account changes."
---

# Migrating from Digital Onboarding

This guide covers Liechtenstein Life Invest. Move offer creation from `/graphql/partner` to `/graphql/partner-platform`.
Keep your existing Partner Life link. Continue completing and submitting the
application in Partner Life.

## 1. Change the endpoint

Use the same API base URL as your existing integration. For testing, use Stable.

| Setting | Old API | New API |
|---|---|---|
| Endpoint | `/graphql/partner` | `/graphql/partner-platform` |
| Authorization | `Bearer <PARTNER_API_TOKEN>` | Same token mechanism; use your partner API token |
| Broker header | May already be present | Always send `x-partner-id: <BROKER_ID>` |
| Offer operation | `createOffer(input:)` or `createUser(user:)` | `createOffer(input:)` |

## 2. Move the fields

Use the table for the operation you call today. The new operation is always
`createOffer(input:)`.

### If you currently use createOffer

All paths below start inside the mutation's `input` argument.
For the new API, `LLI` means `liechtensteinLifeInvest`.

| Old field | New field | What to do |
|---|---|---|
| `customer.newCustomer` | `LLI.associatedPersons[].person.newCustomer` | Move the customer into the persons list. |
| `customer.customerId` | `LLI.associatedPersons[].person.existingCustomer.byID.ID` | Use this instead when the customer already exists. |
| `insuranceProductConfiguration.liechtensteinLifeInvest.policyConfiguration` | `LLI.productConfiguration` | Move `startDate`, `ageWhenPolicyEnds`, `monthlyPremium`, and `additionalPayment` here. |
| `insuranceProductConfiguration.liechtensteinLifeInvest.investmentStrategy` | `LLI.productConfiguration.investmentStrategy` | Move the investment details here. Apply the sustainability changes below. |

Inside `person.newCustomer`:

| Old customer field | New customer field | What to do |
|---|---|---|
| `email`, `firstName`, `lastName` | Same names | Keep the values. |
| `dateOfBirth`, `gender`, `maritalStatus`, `nationality`, `address` | Same names | Keep the values. |
| `taxIdentification` | `taxIdentification` | Required for a new policyholder. |
| `profession.profession` | `profession` | Send a string. This is now required. |
| `profession.occupation` | `occupation` | Send a string if available. |
| `phoneNumber.value` | `mobilePhone` | Send the international phone number as a string. |
| `locale` | `LLI.productConfiguration.language` | Move this outside the customer. Map `DE` to `DE_DE` or `EN` to `EN_US`. |
| `genderAtBirth`, `consumerAppConfiguration` | No matching fields | Remove these from the offer request. |

### If you currently use createUser

Old paths below start inside `user`. New paths start inside `input`.
For the new API, `LLI` means `liechtensteinLifeInvest`, and `person` means
`LLI.associatedPersons[].person.newCustomer`.

| Old field | New field | What to do |
|---|---|---|
| `email`, `firstName`, `lastName`, `address`, `taxIdentification` | Same names under `person` | Move the customer details here. |
| `personalDetails.dateOfBirth`, `personalDetails.gender`, `personalDetails.maritalStatus`, `personalDetails.nationality` | `person.dateOfBirth`, `person.gender`, `person.maritalStatus`, `person.nationality` | Remove the `personalDetails` wrapper. |
| `professionV2.profession`, `professionV2.occupation` | `person.profession`, `person.occupation` | Send strings. `profession` is required. |
| `phoneNumber.value` | `person.mobilePhone` | Send the international phone number as a string. |
| `policyConfigurationV2` | `LLI.productConfiguration` | Move the existing policy settings here. |
| `investmentStrategy` | `LLI.productConfiguration.investmentStrategy` | Move the investment details here. |
| `income` | `LLI.customerFinancialStatus` | Move the financial details. Income and expenses are now required. |
| `paymentMethod` | `LLI.customerFinancialStatus.paymentMethod` | Move the payment choice here. For direct debit, also send `accountHolder`. |
| `health` | `LLI.insuredPersonsHealthStatus` | Move the health answers here. |
| `lifeBenefit`, `deathBenefit` | `LLI.beneficiaries.lifeBeneficiary`, `LLI.beneficiaries.deathBeneficiary` | Rebuild beneficiary details using the new input types. |
| `locale` | `LLI.productConfiguration.language` | Map `DE` to `DE_DE` or `EN` to `EN_US`. |
| `acceptedTermsAt`, `verifiedEmailAt`, `externalIdentityVerification`, `personalDetails.genderAtBirth` | No matching fields | Remove these from the offer request. |

The LLI contract language accepts `DE_DE`, `EN_US`, or `DE_CH`. Old `FR` and `IT`
locale values have no matching contract language. Agree the document language
before switching those customers.

### Sustainability fields

These paths are relative to `investmentStrategy.sustainabilityDetails`.

| Old field | New field | What to do |
|---|---|---|
| `userKnowledgeStatus` | `customerKnowledgeStatus` | Rename the field. |
| `productConfigurationV2.percentage` | `percentage` | Remove the `productConfigurationV2` wrapper. |
| `productConfigurationV2.topicsToInclude` | `topicsToInclude` | Remove the wrapper. |
| `productConfigurationV2.topicsToExclude` | `topicsToExclude` | Remove the wrapper. |
| `productConfigurationV2.environmentalAndSocialInvestmentFocusLevel` | `environmentalAndSocialInvestmentFocusLevel` | Remove the wrapper. |

If you still use the older `productConfiguration.aims` input, contact us for the
mapping before switching.

## 3. Add the required fields

All paths below start inside `input.liechtensteinLifeInvest`.
Some fields are new. Others were optional in the old API and are now required.
If you already collect a value, move the actual value into the new field.

| Required field | What to send |
|---|---|
| `associatedPersons[].role` | Assign all five roles: `POLICY_HOLDER`, `INSURED_PERSON`, `PAYER`, `MAILING`, and `ECONOMIC_INTEREST`. One person can hold all five when that matches the application. |
| `associatedPersons[].person.newCustomer.dateOfBirth`, `gender`, `maritalStatus`, `nationality`, `address` | Required for a new customer. The old `createUser` request could omit these details. |
| `associatedPersons[].person.newCustomer.profession` | The customer's profession. Required when creating a new customer. |
| `associatedPersons[].person.newCustomer.taxIdentification` | Tax information for a new policyholder. The policyholder also needs an email address. |
| `customerFinancialStatus.policyReason` | The reason for the contract, such as `PRIVATE_PENSION`. |
| `customerFinancialStatus.moneyOrigin` | The source of the premiums, such as `EARNED_INCOME`. |
| `customerFinancialStatus.totalMonthlyNetIncome` | Monthly net income in EUR cents. |
| `customerFinancialStatus.totalMonthlyExpenses` | Monthly expenses in EUR cents. |
| `customerFinancialStatus.paymentMethod` | Either `wireTransfer: true` or `directDebit: { iban, accountHolder }`. |
| `insuredPersonsHealthStatus.hasCriticalIllness` | The insured person's actual answer: `true` or `false`. |
| `productConfiguration.deathCoveragePercentage` | The death coverage percentage selected for the application. |
| `productConfiguration` | Supply `startDate`, `ageWhenPolicyEnds`, `monthlyPremium`, `additionalPayment`, and `investmentStrategy`. These details can no longer be omitted. |
| `productConfiguration.investmentStrategy` | Supply `goals`, `riskLevel`, `sustainabilityDetails`, and `fundSelection`. Include `customerKnowledgeStatus` and `percentage` in the sustainability details. |

If `hasCriticalIllness` is `true`, also send `criticalIllnessDetails`.
If `policyReason` or `moneyOrigin` is `OTHER`, send the corresponding
`policyReasonOtherText` or `moneyOriginOtherText`.

Send these required values when creating the offer, before opening Partner Life.
Do not use placeholder answers for customer declarations.

### Keep the units correct

- Money uses EUR cents: `10000` means EUR 100.00. Values from the old
  `policyConfigurationV2` already use cents.
- If you still use the deprecated `policyConfiguration` input on `createUser`,
  its amounts use euros. Convert those amounts to cents once.
- Dates use `YYYY-MM-DD`.
- Fund percentages must total 100, with no duplicate funds and at most 10 funds.
- Send `rebalancingType` explicitly to preserve your current choice. Without a
  partner-specific default, the old `createOffer` uses `NONE` and the new API uses
  `NORMAL` when the field is omitted.

## 4. Update the response handling

| Old API | New API |
|---|---|
| `createOffer` returns `OfferResponse.offerId` and `customer` | `createOffer` returns `CreatedOffer.contractID` |
| `createUser` can return a customer `magicLinkUrl` | Offer creation does not return a customer login link |
| `createUser` creates the customer online account during onboarding | For new customers in this flow, the customer online account is created during policy pickup |

A customer record on an offer is separate from the customer online account.
Keep the Partner Life login link for the broker. Remove any step that expects a
customer login link from offer creation.

### Match existing customer IDs

| ID from the old API | Field in the new `customer` response | Meaning |
|---|---|---|
| `createUser.id` or `user.id` | `consumerID` | The customer online account ID. This can be `null` when no customer online account is linked yet. |
| `createOffer.customer.id` or `customer.id` | `ID` | The person ID. Use this for Platform API customer lookups and existing-customer offer requests. |

Look up the customer by email to read both IDs:

```graphql
query CustomerIDs($email: Email!) {
  customer(input: { email: $email }) {
    __typename
    ... on CustomerInterface {
      ID
      consumerID
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

Match `consumerID` against the consumer ID you already store. Store `ID` for new
Platform API requests. Do not replace one with the other.

### Read the creation result

Use this mutation for the new API:

```graphql
mutation CreateLLIOffer($input: CreateOfferInput!) {
  createOffer(input: $input) {
    __typename
    ... on CreatedOffer {
      contractID
    }
    ... on ErrorInterface {
      message
    }
    ... on InputValidationError {
      invalidInput
    }
  }
}
```

Store `contractID` on success. Handle error results using `__typename` and
`message`. Check top-level GraphQL errors as well.

## 5. Keep the Partner Life handoff

1. Create the offer through the new API.
2. Keep the existing wait until the offer is available in Partner Life.
3. Open Partner Life using your existing login and offer link.
4. Complete and submit the application in Partner Life as you do today.

Check which identifier your existing offer link needs. The new creation result is
`contractID`; the old `offerId` field is not returned. Do not assume these values
are interchangeable.

The customer online account is created during policy pickup. No customer login
step is needed when you create the offer.

---

## Policies

URL: https://partner.life.li/integration-docs/platform-integrations/policies

# Policies

The `policies` query returns the policies connected to your account, along with the premium each one pays, what the insurer values it at, and the fund units it currently holds. Use it to reconcile your own system against ours, or to show a broker their portfolio.

It requires the `POLICY_READ` permission on your API key — contact support to have it enabled.

## Fetching policies

Results are ordered by policy number and paginated with cursors. Omit `pagination` to get the first 50.

```graphql
query Policies($pagination: PoliciesPaginationInput, $includeSubPartners: Boolean = false) {
  policies(pagination: $pagination, includeSubPartners: $includeSubPartners) {
    __typename
    ... on PoliciesConnection {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        cursor
        node {
          id
          active
          pickedUpAt
          firstPremiumStatus
          regularPremium {
            amount
            currency
            frequency
          }
          fundValue {
            amount
            currency
            valuationDate
          }
          fundAllocation {
            valuationDate
            funds {
              isin
              units
              isLoyaltyFund
            }
          }
        }
      }
    }
    ... on UnauthorizedOperationError {
      message
    }
    ... on RateLimitedError {
      message
      retryAfterSeconds
    }
    ... on InputValidationError {
      invalidInput
      message
    }
    ... on UnexpectedError {
      message
    }
  }
}
```

```json
{
  "pagination": { "first": 50 },
  "includeSubPartners": false
}
```

**Response**

```json
{
  "data": {
    "policies": {
      "__typename": "PoliciesConnection",
      "totalCount": 128,
      "pageInfo": { "hasNextPage": true, "endCursor": "FL-1234567" },
      "edges": [
        {
          "cursor": "FL-1234567",
          "node": {
            "id": "FL-1234567",
            "active": true,
            "pickedUpAt": "2026-07-29T14:30:00.000Z",
            "firstPremiumStatus": "RECEIVED",
            "regularPremium": { "amount": 33000, "currency": "CHF", "frequency": "MONTHLY" },
            "fundValue": {
              "amount": 1234567,
              "currency": "CHF",
              "valuationDate": "2026-07-29"
            },
            "fundAllocation": {
              "valuationDate": "2026-07-29",
              "funds": [
                { "isin": "LU0552385295", "units": 142.8317, "isLoyaltyFund": false },
                { "isin": "LU0552385295", "units": 3.1104, "isLoyaltyFund": true }
              ]
            }
          }
        }
      ]
    }
  }
}
```

## What we provide

| Field | Description |
| --- | --- |
| `id` | The policy number, e.g. `FL-1234567`. Identical to the `contractID` of the offer it was issued from, and to the edge's `cursor`. |
| `active` | Whether the policy is currently in force. `false` once terminated or otherwise inactive. |
| `pickedUpAt` | Recorded digital pickup date and time. `null` means no pickup is recorded. See [Digital policy pickup](#digital-policy-pickup). |
| `firstPremiumStatus` | Whether the policy's first premium has reached the insurance system, and — where it has not — what the policyholder has said about it. |
| `regularPremium.amount` | The size of one payment, in the smallest unit of its currency — `33000` is 330.00. One payment, not a yearly figure and not a total. |
| `regularPremium.currency` | The ISO 4217 code the amount is denominated in, `CHF` or `EUR`. Read it before you book the amount. |
| `regularPremium.frequency` | How often the payment falls due: `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY` or `ANNUALLY`. The same four cadences `createOffer` accepts. |
| `fundValue.amount` | What the policy's holdings are worth, in the smallest unit of its currency — `1234567` is 12,345.67. |
| `fundValue.currency` | The ISO 4217 code the amount is denominated in. Always the policy's own currency. |
| `fundValue.valuationDate` | The day the amount is as of. See [Fund values and how fresh they are](#fund-values-and-how-fresh-they-are). |
| `fundAllocation.valuationDate` | The day the holdings are as of. The insurance system values per calendar day and typically lags a few business days, so this is normally not today. |
| `fundAllocation.funds` | One entry per (`isin`, `isLoyaltyFund`) pair — a fund held both as a regular position and as loyalty units appears twice. Each entry carries the ISIN, the number of units (fractional), and whether it is the insurer's loyalty fund (_Treuefonds_). |

`regularPremium` is the premium the policy pays today, not the one its offer was written with — premiums are indexed, paused and rewritten over a policy's life. Amount and cadence stay separate rather than combined into a yearly or lifetime figure, so the total your side books is one you defined. It is `null` when no recurring premium is due: a single-premium contract, a policy that is paid up, or one that has run past its premium-paying term.

`fundValue` is priced from the same unit holdings `fundAllocation` publishes, so the units multiply out to it, and it is the same figure the policyholder sees in their app. `0` is a valuation; `null` means nothing has been valued yet.

`fundAllocation` is `null` when we hold no valuation for the policy — usually because there is none to hold (no premium invested yet, or a product with no investment component).

Any nullable field on a policy can also be `null` because we could not read it, and the response then carries an entry in its `errors` array naming the policy and the field. Check `errors` before you treat a `null` as an empty portfolio, as a policy that pays nothing, or as one the insurer has never valued.

The query names no person. Policy numbers, premiums and fund holdings are still personal data about the policyholder under the GDPR, and must be handled inside your data-processing agreement.

## Digital policy pickup

`pickedUpAt` is the recorded date and time when the policyholder confirms digital receipt of the policy. A non-null timestamp means the policy is picked up. `null` means no digital pickup is recorded.

App registration, inbox confirmation, a document download, and payment of the first premium are separate events. None of them alone sets `pickedUpAt`. This status does not change postal delivery settings or prove that a postal delivery occurred.

Existing pickup dates are available through this query without waiting for a new event. Check the response's `errors` array before treating `null` as a policy awaiting pickup.

Subscribe your existing webhook URL to [`POLICY_PICKED_UP`](https://partner.life.li/integration-docs/platform-integrations/webhooks#policy_picked_up) for notifications of new pickups. Reconcile the policy state through `policies` when you receive a notification and periodically to recover missed deliveries.

## Fund values and how fresh they are

Each policy's holdings are priced daily: its fund units are multiplied by the funds' own closing prices and converted into the policy's currency. `valuationDate` is the day that produced `amount`.

Fund prices reach us once a day and unit holdings a few times a day, so `valuationDate` is normally the most recent business day rather than today. There is no intraday figure to ask for — requesting the field more often returns the same number until the next pricing run.

Where a policy holds loyalty units (_Treuefonds_), `amount` includes them. The insurer credits those on its own schedule, so for such a policy `valuationDate` can be a later day than `fundAllocation.valuationDate`, which names the regular holdings' day.

### The read budget

Selecting `fundValue` draws on a per-broker budget of **100 requests per 30 minutes** — each broker you act for carries its own. One request costs one unit whatever its page size, so a window covers 5,000 policies at the default 50 a page, or 10,000 at the maximum 100. A request that omits the field costs nothing.

If that does not fit your integration, tell us what you need: the ceiling is set per partner, and raising yours does not require a release.

### When the budget runs out

A request over the budget returns `RateLimitedError` and **no policies**.

```json
{
  "data": {
    "policies": {
      "__typename": "RateLimitedError",
      "message": "This broker has read more policy valuations than its budget allows in the current window. No policies were returned.",
      "retryAfterSeconds": 842
    }
  }
}
```

**Wait `retryAfterSeconds` before you retry.** A retry inside the window consumes nothing and returns this same error, so a loop that retries immediately will still be looping when the window resets — and will spend the new budget in seconds.

If you expect to approach the ceiling, pace your own calls against the window rather than relying on being refused — and tell us if your volume needs a higher one.

## Your own policies or your whole tree

With `includeSubPartners` left at `false`, as in the query above, you get only the policies of the broker in the `x-partner-id` header. Flip the variable to include every broker below that one in the hierarchy:

```json
{
  "pagination": { "first": 50 },
  "includeSubPartners": true
}
```

That widens the result to the whole sub-tree and requires the additional `POLICY_TREE_READ` permission — without it the query returns `UnauthorizedOperationError`.

## Paging through the book

Page in one direction at a time: `after` with `first` to go forwards, `before` with `last` to go backwards. Mixing the two returns an `InputValidationError` with `invalidInput: PAGINATION_CONFLICTING_ARGUMENTS`. A page holds at most 100 policies.

The cursor is the policy number itself, so you can resume from an ID you already stored. If that policy is no longer readable — inactive policies are eventually removed — you get `PAGINATION_CURSOR_NOT_FOUND` rather than an empty page. Restart the walk without a cursor.

Full field-by-field reference: [Schema Reference](https://partner.life.li/integration-docs/docs/schema).

---

## Creating and listing pre-registrations

URL: https://partner.life.li/integration-docs/platform-integrations/pre-registrations

# Creating and listing pre-registrations

Use `createPreRegistration` to prepare an Altersvorsorgedepot Plus pre-registration for a German resident directly from your platform. It applies the same validation, broker attribution and email rules as Partner Life. Submit the complete answers after the broker's conversation with the customer; keep intermediate states in your own system.

This step creates no insurance-system offer or app account. The result depends on the customer's relationship to the broker:

| Customer | Input choice | Result |
|----------|--------------|--------|
| Existing customer with an app account | `existingCustomer` | `CreatedPreRegistration`: answers are saved on that account, then the API tries to send the usual preparation email. |
| Existing customer without an app account | `existingCustomer` | `PreRegistrationInvitationSent`: answers wait behind an invitation addressed to the email on record. |
| New customer | `newCustomer` | `PreRegistrationInvitationSent`: answers wait behind an invitation addressed to the supplied email. |

`CreatedPreRegistration` confirms that the record was saved. Preparation email sending is best-effort: a missing recipient or a mail-provider failure can leave the saved record without an email. The customer can still find it in the app. Neither success result confirms mailbox delivery; do not resubmit the mutation to retry an email.

For an invitation, the pre-registration is created in the account only after the recipient signs in or registers, verifies their email and confirms their identity. Existing accounts are preserved. An existing pre-registration is never overwritten.

## AI integration prompt

Copy this prompt into your AI coding assistant to implement the existing-customer and new-customer paths. It includes the request, schema types, access rules, email behavior and retry handling from this guide.

## Access and broker attribution

Use the authentication described in [Platform GraphQL API](https://partner.life.li/integration-docs/platform-integrations/graphql-api). Every request needs your API key and an `x-partner-id` header containing the acting broker's Lifeware ID. Your key must be authorized to act for that broker.

Your integration needs `CREATE_OFFER_V2`. The responsible broker must have new-business access and the German market. A colleague acts under their parent broker: the colleague remains the author, while the responsible broker receives the attribution and uses their invitation allowance. The API resolves these relationships; neither a broker ID nor an app user ID belongs in the input.

Pensionfriend and Nettowelt already have the required API permission. Pensionfriend can act for its configured broker IDs; Nettowelt can also act for brokers in its configured broker trees. Both remain subject to the broker and customer access checks above.

The integration's access is checked against the current hierarchy. A colleague with an individual seat can select only customers visible to that seat; a back-office colleague can act for the broker's customer book.

## Complete request

Always request `__typename` and `ErrorInterface.message`, then handle the two success types separately.

```graphql
mutation CreatePreRegistration($input: CreatePreRegistrationInput!) {
  createPreRegistration(input: $input) {
    __typename
    ... on CreatedPreRegistration {
      preRegistrationId
    }
    ... on PreRegistrationInvitationSent {
      invitationId
    }
    ... on ErrorInterface {
      message
    }
    ... on PreRegistrationInputValidationError {
      issues {
        path
        code
        message
      }
    }
    ... on PreRegistrationInvitationRefusedError {
      reason
      retryAt
    }
  }
}
```

The variables below show a new customer with direct subsidy entitlement, no children and no existing pension contracts. Replace the placeholder ISIN with an eligible fund before sending the request. Altersvorsorgedepot Plus takes its funds from the Liechtenstein Life Invest range that `availableFunds(product: LIECHTENSTEIN_LIFE_INVEST)` returns, within the limits listed below the example.

```json
{
  "input": {
    "liechtensteinLifeAVDPlus": {
      "customer": {
        "newCustomer": {
          "firstName": "Alex",
          "lastName": "Example",
          "dateOfBirth": "1990-05-17",
          "gender": "DIVERSE",
          "email": "alex@example.com",
          "address": {
            "street": "Example Street",
            "houseNumber": "1",
            "zip": "10115",
            "city": "Berlin",
            "country": "DE"
          },
          "taxResidencyDE": true
        }
      },
      "contribution": {
        "monthlyContribution": 20000,
        "retirementAge": 67
      },
      "subsidyEntitlement": {
        "type": "DIRECT",
        "employmentType": "EMPLOYED",
        "children": []
      },
      "existingContracts": [],
      "productConfiguration": {
        "payoutForm": "LIFELONG",
        "lumpSumPercent": 0,
        "pensionGuaranteeYears": 0,
        "annualIncreasePercent": 0
      },
      "fundAllocations": [
        {
          "isin": "REPLACE_WITH_ELIGIBLE_FUND_ISIN",
          "percent": 100
        }
      ],
      "invitationDeclaration": {
        "confirmed": true,
        "locale": "EN",
        "mailLocale": "EN"
      }
    }
  }
}
```

`monthlyContribution` is in EUR cents: `20000` means EUR 200 per month. Partner Life's age-dependent contribution minimum and retirement-age rules also apply here. Fund ISINs must be distinct; percentages must be positive whole numbers totalling 100. Each fund must have a known risk class from 1 to 5. Funds under Swiss law (ISINs starting with `CH`) and Liechtenstein Life's internal strategies (IDs starting with `LLA`) are not admitted, although `availableFunds` lists them for Liechtenstein Life Invest. A refused fund is reported under the issue code `fundRiskAboveLimit`, whatever the reason. The placeholder above is not a usable fund selection.

`taxResidencyDE` must be explicitly `true`, and the residence country must be `DE`. For indirect entitlement, supply the spouse's required details and `notPermanentlySeparated: true`. Supply `children: []` and `existingContracts: []` when those lists are empty.

## Existing customers

Replace `customer.newCustomer` with `customer.existingCustomer`. Set `by` to either the customer ID returned by the `customer` query or their email, and put the complete person answers under `person`:

```json
{
  "existingCustomer": {
    "by": {
      "ID": "00000000-0000-4000-8000-000000000001"
    },
    "person": {
      "firstName": "Alex",
      "lastName": "Example",
      "dateOfBirth": "1990-05-17",
      "gender": "DIVERSE",
      "email": "alex@example.com",
      "address": {
        "street": "Example Street",
        "houseNumber": "1",
        "zip": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "taxResidencyDE": true
    }
  }
}
```

Use the real customer ID in place of the example UUID. To identify them by email, use `"by": { "email": "alex@example.com" }` instead. Supply exactly one identifier and exactly one customer choice.

When several customers in scope share an email, the API returns an `ambiguousCustomer` validation issue. Select the person by ID. Existing customers must be natural persons; companies cannot hold a personal pension pre-registration.

The customer must belong to your broker subtree through a current policy, offer or eligible direct broker assignment from `createCustomer`. The API resolves account ownership again before writing. If they have no account, the invitation goes to their email **on record**, even if `person.email` contains a different answer. This operation does not update that stored email.

Selecting an existing customer outside the acting broker's book or colleague seat returns `CustomerNotFoundError`, whether identified by ID or email. The request creates no pre-registration or invitation and sends no email. Authorization to act for several brokers does not combine their customer books: each request uses the scope of its `x-partner-id`.

Use `existingCustomer` for a customer already in your book. A new-customer request naming an email found in your own customer search is refused with `RECIPIENT_IS_EXISTING_CUSTOMER`. An email outside your book receives no account-ownership disclosure.

## Register a customer, then continue in Partner Life

You can instead [register the customer using `createCustomer`](https://partner.life.li/integration-docs/platform-integrations/creating-offers#registering-a-customer) and keep its returned `customerID`. The customer is assigned to the broker selected by `x-partner-id` and can be selected in Partner Life's AVD customer search before an offer or contract exists, subject to the same current broker and colleague access rules.

The broker can then prepare the pre-registration in Partner Life, including the fund selection. Customer registration alone creates no AVD pre-registration, app account or offer and sends no AVD invitation; the pre-registration submission triggers the applicable preparation email or invitation.

## Invitations and deferred details

Include `invitationDeclaration` whenever the recipient needs an invitation. Set `confirmed: true` only when the broker collected these answers in conversation with the customer and the customer knows they will receive an invitation by email. `locale` records the declaration's language; `mailLocale` selects the invitation language and defaults to `DE`. Supported values are `DE`, `EN`, `FR` and `IT`. An existing customer with an app account can omit this declaration.

Invitations retain the submitted answers while the recipient confirms their identity. They expire after 14 days and share Partner Life's limit of 20 creations per responsible broker in a rolling 24-hour window. Partner and recipient eligibility restrictions continue to apply. Treat `PreRegistrationInvitationSent` as an accepted invitation: it does not confirm mailbox delivery or disclose the recipient's account status.

Tax and social-insurance identifiers and bank details can be deferred until signing; supplied identifiers must pass the applicable validation. Bank details grant no SEPA mandate. Final legal acknowledgments and transfer mandates are collected later from the customer, not accepted through this pre-registration API.

## Listing pre-registrations

Use the `preRegistrations` query to read back the Vormerkungen a Vermittler prepared in the broker's tree, whether in Partner Life or through `createPreRegistration`. Entries a colleague prepared before leaving stay listed. It lists these kinds of entry:

- `PreRegistration`: held in a customer's app account. The customer can see and change it in the app.
- `PreRegistrationInvitation`: an invitation waiting for the person to register and claim the answers.

As in Partner Life, pre-registrations a customer filled in themselves are listed too, complete or incomplete, without a copied broker link or its sharing consent. A pre-registration another tree's Vermittler prepared for a customer who is also attributed to your tree is listed, as Partner Life shows it to you too. Your integration needs the `PRE_REGISTRATION_READ` permission. The broker in `x-partner-id` needs the same broker access as for `createPreRegistration`. Pensionfriend has this permission.

```graphql
query PreRegistrations($updatedSince: DateTime, $pagination: PreRegistrationsPaginationInput) {
  preRegistrations(updatedSince: $updatedSince, pagination: $pagination) {
    __typename
    ... on PreRegistrationsConnection {
      edges {
        node {
          __typename
          id
          product
          responsiblePartnerId
          customerEmail
          customerID
          startedAt
          updatedAt
          ... on PreRegistration {
            origin
            complete
            completedAt
            claimedFromInvitationId
          }
          ... on PreRegistrationInvitation {
            state
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

| Field | Description |
|-------|-------------|
| `id` | The entry's stable identifier. Use it as the key in your system. For an entry your integration created, it is the `preRegistrationId` or `invitationId` that `createPreRegistration` returned. A `PRE_REGISTRATION_CREATED` webhook carries the same value. |
| `product` | `LIECHTENSTEIN_LIFE_AVD` or `LIECHTENSTEIN_LIFE_AVD_PLUS`. Null when the product cannot be determined from what is stored. |
| `responsiblePartnerId` | Lifeware ID of the broker in your tree the entry is attributed to. For an entry a broker's colleague prepared, this is the broker. |
| `customerEmail` | The email address of the customer's app account, or for an invitation, the address it was sent to. A change to an account's address does not move `updatedAt`. |
| `customerID` | The ID the `customer` query uses. See below before relying on it. |
| `startedAt` | When the entry was created. For a pre-registration claimed from an invitation, this is when the invitation was claimed. |
| `updatedAt` | For a pre-registration, when its stored answers last changed, which can happen without any listed field changing. For an invitation, when its state last changed. |
| `origin` | `BROKER` when a Vermittler wrote it directly into the account, `INVITATION` when the customer claimed an invitation. |
| `complete`, `completedAt` | Whether every question the pre-registration asks has been answered, and when that happened. Details collected at signing, such as tax and social-insurance identifiers, are not part of this. `completedAt` is occasionally null for a complete pre-registration when that moment is not known. |
| `claimedFromInvitationId` | On a pre-registration claimed from an invitation, that invitation's `id`. |
| `state` | `SENT`, `CLAIMED`, `LAPSED` or `CANCELLED`. `LAPSED` covers every way an invitation ends without being claimed; the reason is not disclosed, because it is about the recipient. |

### Do not key entries on `customerID`

On a pre-registration, `customerID` is null until the customer's app account is linked to a customer in the insurance system. For a prospect a Vermittler invited, that can be well after they claimed the invitation, and it can then appear without `updatedAt` changing. On an invitation, it is set only if the person was already a customer in your tree when it was sent. Key entries on `id`, and treat `customerID` as an optional link to the `customer` query.

### Claimed invitations

When an invited person claims an invitation, two entries describe them: the invitation, now in state `CLAIMED`, and their new pre-registration with its own `id`. The pre-registration names the invitation in `claimedFromInvitationId`, so you can merge the two in your system. No webhook fires for the claim: the new pre-registration arrives through the query, and the invitation's `updatedAt` moves to the moment of the claim.

### Keeping your list in sync

Entries are ordered by `id`, 50 per page by default and at most 100. Page forwards by passing `pageInfo.endCursor` as `pagination.after` while `hasNextPage` is `true`.

1. Note the current time, then read the full list.
2. On each later run, note the time again, then page through the query with `updatedSince` set to the previously noted time less a safety margin of a few minutes. The margin covers clock differences and changes still being saved while you read. An entry may then arrive twice; update it in place by `id`.
3. Subscribe a webhook to [`PRE_REGISTRATION_CREATED`](https://partner.life.li/integration-docs/platform-integrations/webhooks#pre_registration_created) to hear when a Vermittler adds an entry between runs.

Entries can leave the list without notice. A pre-registration is deleted when the customer or a Vermittler withdraws it, or when the customer's account is deleted. An invitation can disappear when its email could not be sent, or when the account of the Vermittler who prepared it is removed. A removed entry leaves the list without a webhook and is not returned by an `updatedSince` read. Changes to an account's email address or `customerID` do not move `updatedAt` either. Re-read the full list from time to time to pick these up.

## Errors and retries

Declared errors appear in `data.createPreRegistration` with their own `__typename`. GraphQL input errors, such as an invalid email or multiple `@oneOf` choices, appear in the top-level `errors` field.

| Result | Action |
|--------|--------|
| `UnauthorizedOperationError` | Check integration permissions, the selected broker's access and German market. |
| `CustomerNotFoundError` | Check the identifier and current broker relationship. |
| `PreRegistrationInputValidationError` | Correct the returned `issues`, using each issue's `path`, `code` and `message`. Paths are relative to `liechtensteinLifeAVDPlus`. |
| `PreRegistrationAlreadyExistsError` | Use the existing pre-registration; this mutation cannot replace it. |
| `PreRegistrationInvitationRefusedError` | Handle `reason` as described below. |
| `UnexpectedError` | Contact support, including the reference when supplied, before retrying. A record or invitation may already exist. |

Invitation refusal reasons are `DECLARATION_MISSING`, `PARTNER_DOES_NOT_ALLOW`, `DAILY_LIMIT_REACHED`, `NO_EMAIL_ON_RECORD`, `RECIPIENT_IS_EXISTING_CUSTOMER` and `SEND_FAILED`. Confirm the declaration, resolve the partner restriction, correct the stored email, select the existing customer or investigate the failed send as appropriate. For `DAILY_LIMIT_REACHED`, `retryAt` gives the earliest next attempt; it is `null` for other reasons.

This mutation has no request idempotency key. Retrying a new-customer request can create another invitation. After a timeout or uncertain response, reconcile the outcome with support before sending the request again.

---

## Quick Offers

URL: https://partner.life.li/integration-docs/platform-integrations/quick-offers

# Quick Offers

A quick offer answers the first question in a sales conversation: what could this contribution grow to? It needs the insured person's date of birth and the premium, not a customer record. `createQuickOffer` returns the projected values year by year and the insurance system's sample-offer PDF in the same response.

A quick offer is a calculation, not an offer. To offer the product to a customer, call [`createOffer`](https://partner.life.li/integration-docs/platform-integrations/creating-offers).

Your account needs the right to sell the product, the same as for `createOffer`.

| Product input | Currency | Tariff selection |
|---------------|----------|------------------|
| `valueInvestVWL` | EUR | Value Invest VWL 2022 |
| `bestValueRent` | EUR | Best Value Rent 2022 |
| `liechtensteinLifeInvest` | EUR | 049-0-LLI 2025 |
| `liechtensteinLifePension` | EUR | 049-0-LL1B 2025 |
| `liechtensteinLifeWealth` | EUR | 049-0-LLW 2026 |
| `prosperityPlusGermany` | EUR | `brokerageFeePayoutMethod: NET` selects 049-0-PPD 2025; `GROSS` selects 049-1-PPD 2025 |
| `prosperityPlus` | CHF | Domestic 041-1-PP3B 2026 |
| `prosperityDuo` | CHF | 041-1-PD3B 2026 |
| `prosperityJunior` | CHF | 041-1-PJ3B 2026 |
| `liechtensteinLifeWealthCH` | CHF | 041-0-LLW3B 2025 |

Prosperity 3a and yourlife netto plus are not currently available through this operation. Cross-border Prosperity Plus is also unavailable: `crossBorderTariffApplicable: true` returns an input error rather than calculating the domestic tariff.

## Calculating a quick offer

Provide exactly one product. For Value Invest VWL the insured person and the policyholder are the same person, so there is a single date of birth.

```graphql
mutation CreateQuickOffer($input: CreateQuickOfferInput!) {
  createQuickOffer(input: $input) {
    __typename
    ... on QuickOffer {
      tariffName
      currency
      endDate
      totalPremiums
      funds {
        isin
        name
        percentage
      }
      projections {
        date
        age
        capital {
          yieldPercent
          amount
        }
        minimumDeathBenefit {
          yieldPercent
          amount
        }
      }
      document {
        __typename
        ... on QuickOfferDocument {
          fileName
          mimeType
          contentBase64
        }
        ... on QuickOfferDocumentUnavailableError {
          message
        }
      }
    }
    ... on InputValidationError {
      invalidInput
      message
    }
    ... on InsuranceSystemError {
      message
      reasons
    }
    ... on UnauthorizedOperationError {
      message
    }
    ... on UnexpectedError {
      message
    }
  }
}
```

```json
{
  "input": {
    "valueInvestVWL": {
      "insuredBirthdate": "1990-01-01",
      "startDate": "2026-11-01",
      "durationInYears": 30,
      "monthlyPremium": 4000,
      "fundIsin": "LLA035"
    }
  }
}
```

| Field | Meaning |
|-------|---------|
| `insuredBirthdate` | Date of birth of the insured person. |
| `startDate` | When the policy would start. Use the first of the next month if the customer has no wish. |
| `durationInYears` | Length of the policy. The insurance system checks it against the insured person's age. |
| `premiumDurationInYears` | Years the premium is paid. Defaults to `durationInYears` and cannot be longer. |
| `monthlyPremium` | Monthly premium in the smallest monetary unit (cents for EUR). The premium per year (12 times this amount) must be between EUR 168 and EUR 3,000, and together with `additionalPayment` at most EUR 3,000. |
| `additionalPayment` | One-time payment at the start, in the smallest monetary unit. Defaults to `0`. Otherwise at least EUR 50. |
| `fundIsin` | ISIN of the fund. Take it from [`availableFunds`](https://partner.life.li/integration-docs/platform-integrations/funds). |
| `guarantee` | Capital guarantee level. Defaults to `NO_GUARANTEE`. |

### Best Value Rent

Use the same mutation with `bestValueRent`. The calculation uses tariff `best value rent 2022`, EUR, one fund and no separate compensation agreement. No health answers, customer names or addresses are needed.

```json
{
  "input": {
    "bestValueRent": {
      "insuredBirthdate": "1991-11-01",
      "startDate": "2026-11-01",
      "durationInYears": 30,
      "monthlyPremium": 20000,
      "fundIsin": "LU0159549145",
      "guarantee": "NONE"
    }
  }
}
```

Choose a current fund from `availableFunds` with `product: BEST_VALUE_RENT`. Choose a start date from today to three months ahead. The example fund is a test allocation, not a recommendation.

| BVR field or rule | Meaning |
|-------------------|---------|
| `policyholderBirthdate` | Supply it when the policyholder is a different person. Otherwise the calculation uses `insuredBirthdate` for both roles. |
| Ages | Insured age 0–63 at entry and at most 85 at maturity; policyholder age 18–80 at entry. A minor insured therefore needs an adult policyholder. |
| `monthlyPremium` | At least 5000 cents for monthly premiums. Set 0 for a single premium. |
| `additionalPayment` | Defaults to 0. At least 10000 cents when added to monthly premiums, or 200000 cents for a single premium. |
| `durationInYears` | At least 12 years. |
| `premiumDurationInYears` | Defaults to the policy term for monthly premiums; at least five years, ending by insured age 75 and no later than maturity. Omit for a single premium. |
| `guarantee` | `NONE` (default), `SELECT50`, or `SELECT80`. Monthly guarantees require both persons aged 18–47, at least 20 years of policy term and premiums, and payments ending by policyholder age 67. Single-premium guarantees require both persons aged 18–55. |

For a EUR 2,000 single premium, set `monthlyPremium: 0` and `additionalPayment: 200000`, and omit `premiumDurationInYears`. To add a EUR 100 initial payment to monthly premiums, set `additionalPayment: 10000`.

The result has the same `QuickOffer` shape as VWL, with `tariffName: "best value rent 2022"` and `fileName: "quick-offer-best-value-rent.pdf"`. Pension projections are in the sample PDF. The structured response contains capital and minimum death-benefit scenarios. The quick calculation does not include dynamic premium increases or premium waiver; those belong to the full offer.

### Example VWL response

```json
{
  "data": {
    "createQuickOffer": {
      "__typename": "QuickOffer",
      "tariffName": "value invest VWL 2022",
      "endDate": "2056-11-01",
      "totalPremiums": 1440000,
      "funds": [
        { "isin": "LLA035", "name": "prosperity balanced II trust EUR", "percentage": 100 }
      ],
      "projections": [
        {
          "date": "2027-11-01",
          "age": 37,
          "capital": [
            { "yieldPercent": 0, "amount": 27234 },
            { "yieldPercent": 3, "amount": 27744 },
            { "yieldPercent": 6, "amount": 28251 }
          ],
          "minimumDeathBenefit": [{ "yieldPercent": 3, "amount": 720000 }]
        }
      ],
      "document": {
        "__typename": "QuickOfferDocument",
        "fileName": "quick-offer-value-invest-vwl.pdf",
        "mimeType": "application/pdf",
        "contentBase64": "JVBERi0xLjUK..."
      }
    }
  }
}
```

All amounts are in the smallest monetary unit of the returned `currency`: cents for EUR or Rappen for CHF. `projections` has one entry per policy year, oldest first. The response above is shortened to one year.

## Additional products

The additional products use the same common fields: `insuredBirthdate`, `startDate`, `durationInYears`, `premiumDurationInYears`, `monthlyPremium`, `additionalPayment`, and `fundIsin`. Amounts use the product's minor units. These calculations use one fund, monthly recurring premiums, no capital guarantee, no premium waiver and the tariff's standard death-cover rule. Product eligibility still applies; a successful quick offer is not underwriting approval.

### Quick-offer eligibility limits

The supported quick-offer subset uses tariff metadata captured from the insurance system. It is not a promise that the same inputs pass a later application.

| Product | Quick-offer limits |
| --- | --- |
| Invest and Pension | At least EUR 600 annual recurring premiums. A nonzero initial payment alongside recurring premiums is at least EUR 100. The current application validators instead require EUR 1,200 annually and EUR 10,000 for a nonzero initial payment. Reconcile those application requirements before proceeding from a sample calculation. |
| Pension | Premium payments must end by age 75, including when the premium term defaults to the policy term. |
| Domestic Prosperity Plus | This operation supports policy and premium terms of at least 30 years and entry through age 64, and maturity by age 85. All bounds apply together. The broker guide describes a broader range; these narrower limits follow the captured `041-1-PP3B 2026` metadata for `no_guarantee`. Shorter terms or older entry ages are outside this quick-offer subset. |

The EUR 10,000 minimum for a single premium without recurring premiums is distinct from the EUR 100 additional payment in the captured tariff metadata. These additional product inputs currently require recurring premiums.

For Duo and Junior, also supply `policyholderBirthdate`. This is the adult policyholder and insured provider. `insuredBirthdate` belongs to the protected person, or the child for Junior. Do not exchange these roles. Liechtenstein Life Pension also returns maturity pension figures in `pension`; yearly `projections` contain capital and minimum death-benefit scenarios.

```json
{
  "input": {
    "prosperityPlusGermany": {
      "insuredBirthdate": "1996-10-28",
      "insuredFirstName": "Testperson",
      "insuredLastName": "Musterfall",
      "startDate": "2026-11-01",
      "durationInYears": 37,
      "monthlyPremium": 20000,
      "fundIsin": "IE00B5BMR087",
      "brokerageFeePayoutMethod": "NET"
    }
  }
}
```

Use an eligible fund from `availableFunds` for the selected product. Example funds and amounts demonstrate the request format; they are not recommendations.

## Partner pricing and annual fee reductions

Existing requests retain the standard calculation. Set `applyPartnerPricing: true` to forward the product's configured partner pricing terms. Omitted, `null` or `false` leaves configured terms unset. This selects pricing terms only; it does not make every full-offer setting identical.

Value Invest VWL, Liechtenstein Life Invest, Pension and Wealth (Germany) also accept `absoluteReductionFundAdministrationCost`, using the same public name as full offers. The API uses the full-offer **percentage-point convention**, from 0 to 1, and forwards the numeric value unchanged. This input is not a currency amount or a relative discount percentage.

The applied quick-offer fee is not returned in JSON or disclosed numerically in the reviewed PDFs. Equivalence with the full-offer charge remains unverified. Do not derive or communicate an exact annual charge from this input. Confirm the applied charge with the insurance system before relying on pricing equivalence. Pricing terms are tariff-specific: a value inside the input range can still be refused, and acceptance alone does not prove a projection or charge changes.

| Inputs | Pricing selection |
|--------|-------------------|
| No pricing inputs | Standard calculation; no configured partner terms |
| `applyPartnerPricing: true` | Configured partner factors and the product's applicable configured absolute reduction |
| Explicit absolute reduction | That reduction, even without `applyPartnerPricing`; other partner factors remain unset |
| Explicit reduction and `applyPartnerPricing: true` | Explicit reduction overrides the configured absolute reduction; other configured factors remain selected |
| Explicit reduction `0` | No absolute reduction; does not cancel other explicitly selected partner factors |
| Reduction omitted or `null` | Configured absolute reduction only when partner pricing is selected |

The absolute reduction does not require 0.01 increments. Swiss partner factors use a separate mechanism. Swiss inputs do not expose the German absolute reduction. Do not display a Swiss factor as a fee reduction percentage.

## Optional Invest simulation settings

Liechtenstein Life Invest alone accepts `simulation`. Leave the object or either field unset to let the insurance system generate that setting. No default yield is inserted by this API.

```json
{
  "averageYieldPercent": 5.5,
  "absoluteSpreadPercent": 2
}
```

Place this object under `liechtensteinLifeInvest.simulation`. `averageYieldPercent` accepts 3 through 6, including fractional values. `absoluteSpreadPercent` accepts exactly 1, 2 or 3 percentage points. The example selects 3.5%, 5.5% and 7.5% scenarios. Gross/net modes and relative spreads are unavailable. Read the returned yields as the effective scenarios.

## Compatibility

Existing VWL and Best Value Rent inputs remain valid. Existing response fields, monetary units and calculation defaults remain unchanged. `currency` is an additive response field. The adapter accepts both Lifeware projection formats and returns the same `capital` and `minimumDeathBenefit` arrays. Existing callers need no response migration.

## Reading the projections

Each entry in `capital` is the projected fund value at `date` if the funds earned a constant `yieldPercent` per year over the whole term. The entries are scenarios, not a forecast and not a guarantee. Show them together and never present one of them as the expected result. The risk notes in the sample-offer PDF belong with the figures when you show them to a customer.

Leave yield settings unset to use the scenarios generated by the insurance system, as in the app. Read each returned `yieldPercent`; do not assume three fixed rates across products. A rate of `0.75` means 0.75%, not 75%.

For Value Invest VWL you cannot choose between a calculation with and without fund costs.

`minimumDeathBenefit` is the minimum death benefit calculated by the insurance system for each listed yield. It can be empty. The benefit rule depends on the product. In the VWL example above, it follows a fixed share of the agreed premiums early in the term. Do not apply that rule to BVR: use its sample-offer PDF. Show the value as a minimum, never as the amount that will be paid.

Partner pricing is off unless explicitly selected. Additional death cover and other full-offer settings can also differ. A later full offer can therefore produce different figures, even when partner pricing is selected.

## The sample-offer PDF

`document` carries the insurance system's own sample-offer PDF, base64 encoded, so the figures you show match the document the customer can keep. The PDF states how long the proposal is valid.

Names are optional. Supply `insuredFirstName` and `insuredLastName` to name the insured person in the sample PDF. Omitted names use the insurance system's placeholders. When the policyholder is the insured person, that name also appears for the policyholder. Separate policyholder names cannot be supplied through this operation.

The PDF remains a sample calculation, including when it contains a name. Test environments mark it "TEST". Collect names only when needed and protect the returned PDF as personal data.

**We do not store the PDF.** It exists only in this response, and no query returns it again. Save it on your side if you need it.

If the calculation succeeds but the PDF cannot be delivered, `document` is a `QuickOfferDocumentUnavailableError` and `projections` are still present. Calling `createQuickOffer` again recalculates and may return the PDF.

## Errors

Handle two error channels. Schema constraints run before the resolver: out-of-range simulation, reduction or term values can produce a top-level GraphQL `errors` entry with `extensions.code: "BAD_USER_INPUT"` and HTTP 400. For example, `averageYieldPercent: 2.9` violates its `@constraint(min: 3)`. The result union is not returned for that failure; inspect the GraphQL errors even when no `data.createQuickOffer` value exists. Multiple constraint failures can appear under `extensions.validationErrors`.

Resolver validation and calculation failures use the result union described below. Clients must handle both channels. The agreed premium sum must fit the safe-integer minor-unit range; independently valid premiums can still exceed that range over the payment term. Returned totals, capital and death-benefit amounts are checked before success logging or PDF retrieval. An invalid response produces `UnexpectedError` after a calculation may already have happened; do not automatically repeat it.

| Result | When |
|--------|------|
| `InputValidationError` | A term, date, premium, role, pricing or simulation setting is invalid. Existing VWL and BVR validation codes remain available. |
| `InsuranceSystemError` | The insurance system rejects the request, for example because of the customer's age, the premium limits, the requested pricing terms or the fund. `reasons` carries its explanation. A fund from `availableFunds` can still be refused for a quick offer. |
| `UnauthorizedOperationError` | Your account may not sell the product. |
| `UnexpectedError` | The calculation failed or the response could not be validated. Contact support before repeating a timed-out calculation; its outcome can be unknown. |

**Note:**
Every call calculates again at the insurance system. We cannot yet say whether it keeps the calculation, so do not tell customers that nothing is stored.

Full field-by-field reference: [Schema Reference](https://partner.life.li/integration-docs/docs/schema).

## Liechtenstein Life Pension: retirement income

For `liechtensteinLifePension` (Basisrente), select `pension` to receive the pension figures at `endDate`. These figures come directly from Lifeware's calculation, alongside the values shown in the sample PDF. They are not annual entries in `projections`.

```graphql
mutation PensionQuickOffer($input: CreateQuickOfferInput!) {
  createQuickOffer(input: $input) {
    __typename
    ... on ErrorInterface { message }
    ... on QuickOffer {
      currency
      endDate
      pension {
        guaranteedAnnuityFactor
        currentDynamicAnnuityFactor
        guaranteedMonthlyPension { yieldPercent amount }
        currentDynamicMonthlyPensionFirstYear { yieldPercent amount }
      }
    }
  }
}
```

Both factors are monthly pension in EUR per EUR 1,000 of fund value, in major units with the precision returned by Lifeware. For example, a factor of `2.55` means EUR 2.55 monthly pension per EUR 1,000 of fund value. `currentDynamicAnnuityFactor` is the dynamic pension factor, not the separate variable pension factor.

Pension scenario amounts use **minor units**, like existing monetary fields: `24416` means EUR 244.16 per month. `guaranteedMonthlyPension` applies the guaranteed factor to the projected fund value for that scenario; the projected fund value and resulting payout are not guaranteed. `currentDynamicMonthlyPensionFirstYear` is the current dynamic monthly pension for the first retirement year, including non-guaranteed surplus assumptions. Do not describe this figure as a guaranteed payout or an annual payment. Read each returned `yieldPercent` and match scenarios by that value.

`pension` is `null` for other products and when Lifeware omits the required pension blocks. Missing figures are not replaced with zero. Invalid supplied pension values follow the existing calculation error channel. No input fields or existing output fields change. Omitting `document` excludes the PDF from the GraphQL response; the backend still downloads it internally.

---

## Partner Life Single Sign-On

URL: https://partner.life.li/integration-docs/platform-integrations/single-sign-on

# Partner Life Single Sign-On

[Partner Life](https://partner.life.li) is the comprehensive portal for partners to manage contracts, support requests, customer information, and policy changes. This guide explains how to integrate your existing authentication system with Partner Life using the Platform GraphQL API.

## Prerequisites

Before you begin, ensure you have:

- Your API Key
- Your Partner ID (the insurance system broker ID, e.g., `123000`, `23330-2`)
- The Partner IDs of your sub-brokers and employee accounts (found in their welcome emails or in the colleague section of your Partner Life account)

## Integration Steps

### 1. Basic Setup

First, set up access to the Platform GraphQL API as described in the [Platform GraphQL API Guide](https://partner.life.li/integration-docs/platform-integrations/graphql-api).

### 2. Generate Magic Links

Use the `createPartnerLifeMagicLink` mutation to generate direct access links to Partner Life:

```graphql
mutation CreatePartnerLifeMagicLink($input: CreatePartnerLifeMagicLinkInput!) {
  createPartnerLifeMagicLink(input: $input) {
    ... on PartnerLifeMagicLink {
      url
    }
    ... on ErrorInterface {
      message
    }
  }
}
```

Example input — logging in the partner identified by the `x-partner-id` header:

```json
{
  "input": {
    "alreadyMultiFactorAuthenticated": true,
    "acceptPartnerLifeTermsAndConditions": true,
    "acknowledgePartnerLifePrivacyPolicy": true
  }
}
```

Example input — logging in a sub-partner or colleague account:

```json
{
  "input": {
    "partnerLifewareId": "123456",
    "alreadyMultiFactorAuthenticated": true,
    "acceptPartnerLifeTermsAndConditions": true,
    "acknowledgePartnerLifePrivacyPolicy": true
  }
}
```

**Note:**
If `partnerLifewareId` is omitted, the magic link is created for the partner identified by the `x-partner-id` request header. To create magic links for sub-partners or colleague accounts, provide their Partner ID in the `partnerLifewareId` field. The target partner must be within your broker tree.

### 3. Authentication Flow

The basic authentication flow works as follows:

```mermaid
sequenceDiagram
    participant B as Broker/Employee
    participant Y as Your Software
    participant P as Platform API
    participant L as partner.life.li
    B->>+Y: Normal Authentication
    Y->>+P: createPartnerLifeMagicLink mutation
    P-->>-Y: Response (with magic link URL)
    Y->>+L: Redirect to magic link URL (auto-login)
    L->>+L: Multi-factor Authentication Check (SMS/Passkey)
```

### 4. Multi-Factor Authentication

If your system already implements MFA, you can skip Partner Life's MFA check by setting `alreadyMultiFactorAuthenticated` to `true`:

```mermaid
sequenceDiagram
    participant B as Broker/Employee
    participant Y as Your Software
    participant P as Platform API
    participant L as partner.life.li
    B->>+Y: Multi-factor authenticated
    Y->>+P: createPartnerLifeMagicLink mutation<br/>(alreadyMultiFactorAuthenticated: true)
    P-->>-Y: Response (with magic link URL)
    Y->>+L: Redirect to magic link URL<br/>(auto-login, no MFA check)
```

**Note:**

## Auto-Activation of Accounts

For partners with a Partner ID but no active Partner Life account, you can automatically activate their account by setting both `acceptPartnerLifeTermsAndConditions` and `acknowledgePartnerLifePrivacyPolicy` to `true`.

Before activating, ensure the partner has accepted:

- [Terms and Conditions](https://partner.life.li/en/terms-and-conditions)
- [Privacy Policy](https://partner.life.li/en/privacy-policy)

**Note:**

## Deep Linking

A magic link accepts a `redirect` parameter — a URL-encoded Partner Life path. The advisor is logged in and lands there instead of on the dashboard.

```
https://partner.life.li/en/magic-link/<Magic Link Token>?redirect=<URL-encoded path>
```

### Destinations

| Path to encode | Where the advisor lands | Creates an offer |
|---|---|---|
| `/my/customers/<Customer ID>` | The customer's record — contact details, contracts, support history | No |
| `/my/offers/new?customerId=<Customer ID>` | The product catalogue, scoped to that customer. Picking a product opens the offer with them already selected | No |
| `/my/offers/<Contract ID>` | An offer you created through the API | No |
| `/my/products/offer/new?product=<Product Code>` | The new-offer screen for one product | **Yes, on arrival** |
| `/my/products/offer/new?product=<Product Code>&customerId=<Customer ID>` | The same, with the customer already selected | **Yes, on arrival** |

The last two write the offer as the page loads. Right when the product is already settled; for an exploratory jump they leave an offer behind for every conversation that went nowhere.

`<Customer ID>` is the ID [`createCustomer`](https://partner.life.li/integration-docs/platform-integrations/creating-offers#registering-a-customer) returns, or the one [`customer`](https://partner.life.li/integration-docs/platform-integrations/creating-offers#looking-up-customer-id) resolves from an email address. `<Contract ID>` comes from `createOffer`. If an ID is unknown, or the broker account is not licensed to reach that customer, the advisor is told so — your software receives no signal either way.

Example, fully encoded:

```
https://partner.life.li/en/magic-link/<Magic Link Token>?redirect=%2Fmy%2Foffers%2Fnew%3FcustomerId%3D<Customer ID>
```

**Note:**
The target carries its own query string, so `?` and `&` inside it must be `%3F` and `%26`. An unencoded `&` ends the `redirect` value and everything after it is dropped: the advisor still arrives, without the customer, and nothing reports it.

### Product Codes

Only the two product-scoped paths need one.

| Product | `PlatformInsuranceProduct` | Product Code |
|---|---|---|
| Liechtenstein Life Invest | `LIECHTENSTEIN_LIFE_INVEST` | `liechtenstein-life-invest` |
| Liechtenstein Life Pension | `LIECHTENSTEIN_LIFE_PENSION` | `liechtenstein-life-pension` |
| Liechtenstein Life Wealth | `LIECHTENSTEIN_LIFE_WEALTH` | `liechtenstein-life-wealth` |
| Prosperity 3a | `PROSPERITY_3A` | `prosperity-3a` |
| Prosperity Plus | `PROSPERITY_PLUS` | `prosperity-plus` |
| Prosperity Plus DE | `PROSPERITY_PLUS_GERMANY` | `prosperity-plus-de` |
| value invest VWL | `VALUE_INVEST_VWL` | `value-invest-vwl` |
| yourlife netto | `YOUR_LIFE_NETTO_PLUS` | `yourlife-netto` |

A code names no tariff, so it survives a product moving to a new tariff generation. The advisor gets the newest generation their account is licensed for; where a cross-border or gross variant exists, the standard tariff is chosen.

## Error Handling

The mutation returns a union type. Always handle the error cases:

| Error Type | Meaning | Resolution |
|---|---|---|
| `PartnerHasNoPartnerLifeAccountError` | Account not yet activated | Set both T&C and privacy policy flags to `true` |
| `PartnerNotFoundError` | Partner ID not found or not in your broker tree | Verify the Partner ID is correct and within your access scope |
| `PartnerHasNoEmailError` | Partner has no email configured | Contact support to set up the partner's email address |
| `UnexpectedError` | Unexpected internal failure | Log the error, optionally retry the request, and contact support if the problem persists |

## Security Best Practices

1. **Protect magic link URLs** — they are single-use authentication tokens. Do not log or cache them.
2. **Use server-side calls only** — never call the API from client-side code; your API key would be exposed.
3. **Validate MFA claims** — only set `alreadyMultiFactorAuthenticated` to `true` when your system has genuinely verified the user with multiple factors.
4. **Minimal scope** — only request magic links for partners within your broker tree. The API enforces this, but your integration should validate upfront.

## Need Help?

If you don't have access to Partner Life or need assistance, contact [partner support](mailto:support@partner.life.li).

---

## Webhooks

URL: https://partner.life.li/integration-docs/platform-integrations/webhooks

# Webhooks

The Platform GraphQL API supports webhooks so your backend receives a real-time HTTP notification when a relevant event occurs for brokers in your tree.

## Registering a webhook

Use the `registerWebhook` mutation to subscribe a URL to one or more events. Registering the same URL a second time merges the event set — you will not create duplicates.

```graphql
mutation RegisterWebhook($input: RegisterWebhookInput!) {
  registerWebhook(input: $input) {
    id
    url
    events
    createdAt
  }
}
```

```json
{
  "input": {
    "url": "https://your-platform.example/webhooks/lla",
    "events": ["OFFER_CREATED", "OFFER_UPDATED", "REWORK_CREATED", "REWORK_UPDATED", "POLICY_ISSUED", "POLICY_PICKED_UP"],
    "verificationSecret": "your-hmac-secret"
  }
}
```

### Listing registered webhooks

```graphql
query Webhooks {
  webhooks {
    id
    url
    events
    createdAt
  }
}
```

### Removing a webhook

```graphql
mutation UnregisterWebhook($input: UnregisterWebhookInput!) {
  unregisterWebhook(input: $input) {
    __typename
    ... on Success {
      status
    }
    ... on WebhookNotFoundError {
      message
    }
  }
}
```

```json
{
  "input": {
    "url": "https://your-platform.example/webhooks/lla"
  }
}
```

## Events

### `OFFER_CREATED`

Fires when an offer is created for any broker in your tree — including offers created directly in the Liechtenstein Life insurance system, not only offers submitted through this API.

**Payload**

```json
{
  "contractID": "PR-123456",
  "offerId": "abc123",
  "brokerLifewareId": "196856",
  "persons": [
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "POLICY_HOLDER" },
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "INSURED_PERSON" }
  ],
  "event": "offer_created"
}
```

| Field | Type | Description |
|---|---|---|
| `contractID` | `string` | The policy / offer reference in the insurance system. Use this as the `contractID` in `offerStatus` queries. |
| `offerId` | `string` | Internal offer identifier. |
| `brokerLifewareId` | `string` | Lifeware ID of the broker who owns the offer. |
| `persons` | `object[]` | Everyone on the offer, as `customerID` and `role` pairs. A person holding several roles appears once per role. Pass a `customerID` to the `customer` query, or to `createOffer` as `existingCustomer.byID.ID`. The list is empty when the insurance system has not yet placed anyone on the offer; no later event is guaranteed to fill it in, so treat an empty list as a prompt to query the offer rather than as something to wait on. |
| `event` | `"offer_created"` | Literal event name. |

**Note:**
The notification fires when the sync pipeline first observes an offer with a `contractID` for its broker. If the offer was already synced without a `contractID`, the notification fires on the sync that first receives that reference. A status change on that same sync is included in the initial offer state and does not produce a separate `OFFER_UPDATED` event. Later tracked changes produce `OFFER_UPDATED` events. Lifeware-direct offers appear when the offer-sync scheduler picks them up.

### `OFFER_UPDATED`

Fires when an already-known offer changes a meaningful field — its offer status, signature status, or application / cancellation date. It does **not** fire on routine re-syncs that change nothing.

**Payload**

```json
{
  "contractID": "PR-123456",
  "offerId": "abc123",
  "brokerLifewareId": "196856",
  "persons": [
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "POLICY_HOLDER" },
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "INSURED_PERSON" }
  ],
  "changedFields": ["offerStatus", "signatureStatus"],
  "event": "offer_updated"
}
```

| Field | Type | Description |
|---|---|---|
| `contractID` | `string` | Policy / offer reference. |
| `offerId` | `string` | Internal offer identifier. |
| `brokerLifewareId` | `string` | Lifeware ID of the broker who owns the offer. |
| `persons` | `object[]` | Everyone on the offer, as `customerID` and `role` pairs. A person holding several roles appears once per role. Pass a `customerID` to the `customer` query, or to `createOffer` as `existingCustomer.byID.ID`. The list is empty when the insurance system has not yet placed anyone on the offer; no later event is guaranteed to fill it in, so treat an empty list as a prompt to query the offer rather than as something to wait on. |
| `changedFields` | `string[]` | Which fields moved since the previous sync (e.g. `offerStatus`, `signatureStatus`). |
| `event` | `"offer_updated"` | Literal event name. |

### `REWORK_CREATED`

Fires when a rework — a request from the insurer for missing information or a correction before the offer can proceed — is opened on an offer/policy in your tree.

**Payload**

```json
{
  "taskId": "3f1c0b7e-1a2b-4c3d-8e9f-000000000000",
  "contractID": "PR-123456",
  "reason": "Passport copy for the insured person is missing",
  "status": "WAITING",
  "openedOn": "2026-06-30T00:00:00.000Z",
  "closedOn": null,
  "event": "rework_created"
}
```

| Field | Type | Description |
|---|---|---|
| `taskId` | `string` | Unique rework identifier. |
| `contractID` | `string` | Policy reference the rework belongs to. |
| `reason` | `string` | Why the rework was raised. |
| `status` | `"WAITING" \| "FROZEN" \| "FINISHED"` | `WAITING` = awaiting your response; `FROZEN` = you replied, internal verification pending; `FINISHED` = resolved. |
| `openedOn` | `string` | Date the rework opened (date-only, serialized as a midnight-UTC ISO timestamp). |
| `closedOn` | `string \| null` | Date the rework closed, or `null` while still open. |
| `event` | `"rework_created"` | Literal event name. |

### `REWORK_UPDATED`

Same payload shape as `REWORK_CREATED`, with `event: "rework_updated"`. Fires when an existing rework changes — typically a `status` transition (`WAITING → FROZEN → FINISHED`). The closing transition arrives as a final `REWORK_UPDATED` with `status: "FINISHED"` and a non-null `closedOn`.

After it closes, the rework no longer appears in the `openReworks` query or in `offerStatus.openReworks` — both of which list only `WAITING` reworks. The webhook is therefore the only way to observe `FROZEN` and `FINISHED` transitions.

**Note:**
Rework events fire when the rework-sync pipeline observes the change. If the related offer has not yet been synced to your tree, the notification is sent on a later sync cycle once the offer is known.

### `POLICY_ISSUED`

Fires once, when an offer/application in your tree is issued as a policy in the insurance system. Like the other events, this is detected by the sync pipeline, so it covers policies issued outside this API too.

**Payload**

```json
{
  "contractID": "PR-123456",
  "offerId": "abc123",
  "brokerLifewareId": "196856",
  "persons": [
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "POLICY_HOLDER" },
    { "customerID": "af2490b7-a779-11f1-93fd-0050568cdbcc", "role": "INSURED_PERSON" }
  ],
  "event": "policy_issued"
}
```

| Field | Type | Description |
|---|---|---|
| `contractID` | `string` | The issued policy reference. Query it via `offer` / `offerStatus`. |
| `offerId` | `string` | Internal offer identifier the policy was issued from. |
| `brokerLifewareId` | `string` | Lifeware ID of the broker who owns the policy. |
| `persons` | `object[]` | Everyone on the offer, as `customerID` and `role` pairs. A person holding several roles appears once per role. Pass a `customerID` to the `customer` query, or to `createOffer` as `existingCustomer.byID.ID`. The list is empty when the insurance system has not yet placed anyone on the offer; no later event is guaranteed to fill it in, so treat an empty list as a prompt to query the offer rather than as something to wait on. |
| `event` | `"policy_issued"` | Literal event name. |

**Note:**

### `POLICY_PICKED_UP`

Fires when digital receipt of a policy is confirmed in the customer app, or when the policy sync first records a pickup reported by the insurance system. It carries the recorded pickup date, which can precede the notification.

Register the event on your existing URL to merge it into that URL's subscriptions. Existing subscriptions remain active. Registering and receiving this event requires `POLICY_READ` in addition to `WEB_HOOK_MANAGEMENT`.

**Payload**

```json
{
  "contractID": "PR-123456",
  "pickedUpAt": "2026-07-29T14:30:00.000Z",
  "event": "policy_picked_up"
}
```

| Field | Type | Description |
|---|---|---|
| `contractID` | `string` | The policy number. Matches `Policy.id` in the `policies` query. |
| `pickedUpAt` | `string` | The recorded digital pickup date and time, serialized as an ISO 8601 timestamp. |
| `event` | `"policy_picked_up"` | Literal event name. |

App registration, inbox confirmation, a document download, and first-premium payment alone do not trigger this event. Pickup notifications do not change postal delivery settings.

Delivery checks the policy's current broker ownership, pickup date, subscription, and integration permission. A policy transfer, removed confirmation, or revoked permission can therefore suppress a queued notification.

This subscription does not replay historical pickups. Read [`Policy.pickedUpAt`](https://partner.life.li/integration-docs/platform-integrations/policies#digital-policy-pickup) through the `policies` query for existing policies and periodic reconciliation. A repeated confirmation or delivery retry can produce the same notification more than once. Deduplicate by (`contractID`, `pickedUpAt`).

### `PRE_REGISTRATION_CREATED`

Fires when a Vermittler in your tree adds an Altersvorsorgedepot Vormerkung: either a pre-registration written directly into a customer's app account, or an invitation sent to someone who has to register first. It fires for Vormerkungen added in Partner Life and through `createPreRegistration` alike. It does not fire when a customer completes a pre-registration in the app on their own, when an invited person claims an invitation, or when a Vermittler edits an existing Vormerkung.

The payload identifies the entry only. Read its details, including the customer's email, with the [`preRegistrations` query](https://partner.life.li/integration-docs/platform-integrations/pre-registrations#listing-pre-registrations).

**Payload**

```json
{
  "id": "6f1b8c2e-4d3a-4f5b-9c7d-2e8a1b0c9d4f",
  "kind": "INVITATION",
  "responsiblePartnerId": "250430",
  "event": "pre_registration_created"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | `string` | The entry's `id` in the `preRegistrations` query. For an entry your integration created, it is the `preRegistrationId` or `invitationId` that `createPreRegistration` returned. |
| `kind` | `"PRE_REGISTRATION" \| "INVITATION"` | `PRE_REGISTRATION` is held in a customer's app account (`__typename: PreRegistration` in the query). `INVITATION` is waiting for the invited person to register (`__typename: PreRegistrationInvitation`). |
| `responsiblePartnerId` | `string` | Lifeware ID of the broker in your tree the entry is attributed to. For an entry a broker's colleague prepared, this is the broker. |
| `event` | `"pre_registration_created"` | Literal event name. |

Registering this event requires the `PRE_REGISTRATION_READ` permission in addition to `WEB_HOOK_MANAGEMENT`.

## Verifying webhook signatures

Every delivery includes an `x-hmac` header: a hex-encoded HMAC-SHA256 of the raw request body, keyed with your **verification secret**.

Pass your verification secret in the `verificationSecret` field when registering a webhook. Keep it secret — it is the only mechanism that proves a delivery came from us.

**Example — Node.js / TypeScript**

```ts

function isValidWebhook(
  body: string,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex")
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  )
}
```

Always compare with a constant-time function (`timingSafeEqual`) to prevent timing attacks.

## Delivery details

| Property | Value |
|---|---|
| Method | `POST` |
| Content-Type | `application/json` |
| `x-webhook-id` | Unique delivery identifier |
| `x-hmac` | HMAC-SHA256 signature (hex) |
| User-Agent | `prosperity-solutions/1.0.0 (+https://api.prosperity.app/partner/v1/webhook)` |
| Retry policy | 5 attempts with exponential back-off (initial delay 5 s) |

Return `2xx` to acknowledge receipt. Any other status code triggers a retry. Failed deliveries are retained; contact support if you need to replay a specific delivery.

## Delivery guarantees

Webhooks are a **best-effort, at-least-once** notification: a delivery may be retried (so the same event can arrive more than once) and, in rare cases, may be missed entirely during an infrastructure incident. Design your integration accordingly:

- **Reconcile, don't rely solely on webhooks.** Treat the GraphQL queries as the source of truth — on receipt, and periodically as a safety net, fetch the authoritative state with `offer(contractID)` / `offerStatus(contractID)` (`policies` for pickup dates, `openReworks` for reworks, `preRegistrations` for Vormerkungen). A missed webhook then self-heals on the next reconciliation.
- **Be idempotent.** The same event may be delivered more than once. Deduplicate on the natural id for the event — `offerId` for offers, `taskId` for reworks, `contractID` for `POLICY_ISSUED`, (`contractID`, `pickedUpAt`) for `POLICY_PICKED_UP`, `id` for `PRE_REGISTRATION_CREATED` — and make your handler safe to run twice.
- **Don't assume ordering.** Events are not guaranteed to arrive in the order they occurred. Use the queried state (e.g. `offerStatus.status`, the rework `status`) as authoritative rather than inferring it from the sequence of webhooks.

**Note:**

## Access requirement

Your API key must have the `WEB_HOOK_MANAGEMENT` permission to register, list, or remove webhooks. Registering `PRE_REGISTRATION_CREATED` also requires `PRE_REGISTRATION_READ`. Registering `POLICY_PICKED_UP` also requires `POLICY_READ`; without the required permission, the whole registration is refused. Contact your integration support contact if a permission is not active on your key.

---

## Embed Our Calculator Widget

URL: https://partner.life.li/integration-docs/widgets/embedded-calculator

# Embed Our Calculator Widget

We offer a powerful and user-friendly calculator widget that can be easily integrated into your website. The widget provides your customers with a seamless experience to understand and customize their pension plans through an interactive simulation graph.

![Calculator](https://partner.life.li/integration-docs/img/calculator.webp)

## Integration Guide

You can integrate our calculator widget into your website as an `<iframe>` using the following URL:

```html
<iframe
  src="https://example.com/widgets/calculator"
  width="100%"
  height="800px"
  frameborder="0"
></iframe>
```

## URL Parameters

The widget can be initialized with default values using URL parameters. Here are the supported parameters:

| Parameter         | Default | Options            | Description                                                                                 |
| ----------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------- |
| graphType         | preTax  | postTax, preTax    | Initializes the widget with the selected graph type. Users can still switch between graphs. |
| initialPayment    | 0       | -                  | Initial payment amount at policy start                                                      |
| monthlyPayment    | 100     | min = 30           | Monthly payment amount                                                                      |
| riskLevel         | high    | high, medium, low  | Initial risk level selection (high: 9%, medium: 6%, low: 3%)                                |
| currentAge        | 25      | min = 18, max = 55 | Customer's current age                                                                      |
| startInXYears     | 0       | -                  | Initializes with start year difference comparison graph if > 0                              |
| ageWhenPolicyEnds | 67      | 67, 75, 85         | Expected policy end age                                                                     |

## Example Usage

Here's an example of embedding the calculator with some predefined parameters:

```html
<iframe
  src="https://example.com/widgets/calculator?graphType=postTax&monthlyPayment=150&riskLevel=medium&currentAge=30"
  width="100%"
  height="800px"
  frameborder="0"
></iframe>
```

## Customization

The widget automatically adapts to your website's layout and provides a responsive experience across different screen sizes. The height can be adjusted based on your needs by modifying the `height` attribute of the iframe.

---