Partner API - User Onboarding Guide

Purpose

This document explains how to onboard a platform user through the Partner API in the test environment: the required step order, which steps are asynchronous, the statuses to wait for, and the most common reasons a step fails.

The requests in order

Run the first seven steps in order. Reset password and update user are post-onboarding operations, run on demand.

Prerequisites

You need your client_id and client_secret, and the Auth URL / API Base URL for your environment - see Partner API Authentication.

General rules

• Order matters. Each step depends on data created by the previous one (access_token -> userId -> documentId -> onboardingId). Run requests top to bottom.
• Most write operations are asynchronous. A 200 response means the command was accepted, not that processing finished. Poll the matching GET endpoint until it reports a terminal status before moving on.
• Statuses to wait for:
  • GET /users/{userId} -> CREATED before uploading the document.
  • GET /v2/documents/{documentId} -> CREATED before starting onboarding.
  • GET /user-onboardings/{onboardingId} -> APPROVED (terminal). PENDING is transient - keep polling.
• access_token from the token request is sent as the authorization header on every subsequent request. If you get 401, request a new token (the old one has expired).
• requestor-id header - required on the document upload and onboarding writes; it is always the acting user's userId.
• German addresses must be real - city + zip must be a matching real pair (e.g. Berlin / 10178), otherwise downstream taxpayer creation fails.

User onboarding flow

1. Get token - POST /oauth2/token (grant_type=client_credentials, content-type: application/x-www-form-urlencoded). Returns the access_token used by all later requests.
2. Create User - POST /users with type: ADMIN, personal data, nationality, mainAddress, and contact. Use a unique email per user; a duplicate email is rejected. Returns userId.
3. Get User - GET /users/{userId}. Asynchronous: poll until status is CREATED before continuing. Returns globalId.
4. Upload IDENTIFICATION_CERTIFICATE - POST /v2/documents (multipart form-data: a document metadata field plus the file, with the Requestor-ID header set to the userId). The file must be a PDF (max ~4 MB). Returns documentId.
5. Get Document - GET /v2/documents/{documentId}. Asynchronous: poll until status is CREATED before starting onboarding.
6. Start Onboarding - POST /user-onboardings with body { "userId": "<userId>" } and the Requestor-ID header set to the same userId. Returns onboardingId.
7. Get Onboarding - GET /user-onboardings/{onboardingId}. Poll until terminal status APPROVED. On failure the response carries the reason - check it before retrying.

Post-onboarding operations

Reset password

• GET /users/{userId}/reset-password triggers a password-reset for the user. Run any time after the user exists.

Update user

• PATCH /users/{userId} updates mutable user fields: lastName, nationalities, mainAddress, contact, status (e.g. INACTIVE), and mfaType (e.g. SMS).
• Send only the fields you intend to change. Re-run GET /users/{userId} to confirm the new values took effect.
• Keep the address rule in mind: if you change mainAddress, the new city/zip must still be a real pair.

Common failure causes - quick checklist