Partner API - Customer Onboarding Guide (Natural Persons & Legal Entities)

Purpose

This document explains how to onboard customers through the Partner API in the test environment: the required step order, which steps are asynchronous, and the most common reasons an onboarding ends REJECTED instead of APPROVED.

It covers these scenarios:

General rules

• Order matters. Each step depends on data created by the previous one. Run requests top-to-bottom.
• Most write operations are asynchronous. A 200/202 response means the command was accepted, not that processing finished. Poll the corresponding GET endpoint (or use webhooks) before moving to the next step.
• Statuses to wait for are terminal statuses. PENDING is transient - never treat the first non-initial status you read as final. Poll until APPROVED / REJECTED / INVALID (onboarding) or CANCELED (offboarding).
• requestor-id header - required on most writes; always the naturalPersonId of the acting person - see Partner API Authentication.
• German addresses must be real - city + zip must be a matching real pair (e.g. Berlin / 10178), otherwise taxpayer creation fails after onboarding.

Natural Person Customer (NPC) flow

1. Create Natural Person - POST /entities/natural-persons. Required: personal data, nationality, tax details (taxId + taxResidency), income/assets data, main address, contact.
2. Create Identification - POST /entities/natural-persons/{naturalPersonId}/identification. Asynchronous: poll GET /entities/natural-persons/{naturalPersonId} until naturalPersonIdentifications is non-empty before continuing. Alternatively use Identification Verification (WEB-ID) - see below.
3. Create Customer - POST /roles/customers with entityType: NATURAL_PERSON and a reference account (valid IBAN required, e.g. DE75512108001245126199).
4. Upload IDENTIFICATION_CERTIFICATE - POST /v2/documents (PDF, ≤4 MB). Asynchronous: poll GET /v2/documents/{documentId} until status CREATED.
5. Sign TERMS_AND_CONDITIONS - POST /v2/documents/sign with partnerDocumentId, naturalPersonId and customerId (required for T&C). Fetch the current active document versions first via GET /partner-documents?isValid=true.
6. Sign DATA_PRIVACY_POLICY - same endpoint, naturalPersonId only (no customerId).
7. Start Onboarding - POST /roles/onboardings with roleType: CUSTOMER, roleId: <customerId>.
8. Wait for result - poll GET /roles/onboardings/{onboardingId} until terminal status, or subscribe to the ONBOARDING_NOTIFICATION webhook. On REJECTED, the response contains validationErrors explaining what is missing.
9. Create products - POST /customers/{customerId}/products (BALANCE_ACCOUNT, CURRENCY_WALLET, DEPOSITORY_ACCOUNT) - only after onboarding is APPROVED.

Identification Verification (WEB-ID) variant

Instead of submitting identification data directly (step 2), you can create an Identification Verification (POST /entities/identification-verifications). This only starts the verification: a manual click-through in the WEB-ID sandbox is required, and the status stays PENDING until that flow is completed.

Legal Entity Customer (LEC) flow

1. Create Natural Person - the future signatory / legal representative.
2. Create Legal Entity - POST /entities/legal-entities. Required: legalForm, register data, NACE sectors, FATCA/CRS declaration, addresses.
3. Create Legal Representative - POST /entities/{legalEntityId}/legal-representatives (the NP's personal data).
4. Create NP Identification - as in the NPC flow (or WEB-ID variant).
5. Create Proxy (SIGNATORY) - POST /roles/proxies linking the NP to the legal entity.
6. Create Customer - POST /roles/customers with entityType: LEGAL_ENTITY and a reference account.
7. Upload legal entity documents - the required set depends on legalForm (see table below).
8. Upload IDENTIFICATION_CERTIFICATE for the signatory NP.
9. Sign T&C + DPP for the signatory NP (fetch current versions first).
10. Start Onboarding - roleType: CUSTOMER, roleId: <customerId>, requestor-id: <naturalPersonId>.
11. Manual review - LEC onboardings require a manual review step; the onboarding stays PENDING until it is completed. Plan for this delay in the test environment.
12. Create products - after APPROVED. DEPOSITORY_ACCOUNT for a legal entity additionally requires a valid W-8 document uploaded first (the W-8 type depends on the entity’s FATCA classification).

Required documents per legalForm

Missing a required document is the most common cause of a REJECTED LEC onboarding - check validationErrors in the onboarding status / webhook payload.

Webhooks instead of polling

Subscribe via POST /webhooks before starting the flow to get pushed status changes instead of polling. Useful event types during onboarding:

• ONBOARDING_NOTIFICATION - onboarding status changes incl. validationErrors
• NATURAL_PERSON_NOTIFICATION / LEGAL_ENTITY_NOTIFICATION - entity status changes
• IDENTIFICATION_VERIFICATION_NOTIFICATION - WEB-ID verification result
• PROXY_NOTIFICATION - proxy status changes
• DOCUMENT_NOTIFICATION - document status changes (upload is async - wait for CREATED before starting onboarding)

Offboarding notes

• Immediate customer offboarding is rejected while the customer has open products. Close all customer products first, then start the offboarding. The rejection arrives asynchronously (webhook/status: VALIDATION_ERROR, "exists not closed product for customer") - the create call itself succeeds.
• Offboarding statuses are also transient: poll until a terminal status (APPROVED / REJECTED / CANCELED / INVALID).
• A created offboarding can be cancelled (DELETE .../offboardings/{offboardingId}) only while it has not been completed.

Common rejection causes - quick checklist