Creating 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:

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.

Access and broker attribution​

Use the authentication described in Platform 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, the German market and Altersvorsorgedepot rollout access. 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.

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 from the fund catalogue available to your broker for Altersvorsorgedepot Plus before sending the request.

{
  "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. 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:

{
  "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.

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.

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.

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.