> For the complete documentation index, see [llms.txt](https://partner.doc.bunq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://partner.doc.bunq.com/documentation/bunq-as-a-service/chapter-2-onboarding/user-onboarding.md).

# User Onboarding

## Step 1: Receiving Onboarding Model of the user

**Endpoint:**

```http
GET /v1/user/{user_id}/user-onboarding
```

`user_id` above is the `granted_by_user.UserPerson.id` from the session on behalf of the user created above. This `user_id` is the one to be used for all subsequent calls.

**Response:**

```json
{
    "Response": [
        {
            "UserOnboarding": {
                "id": 640514,
                "created": "2026-02-10 18:33:16.090017",
                "updated": "2026-02-10 18:33:16.658287",
                "type": "PARTNER_USER_PERSON",
                "user_status_desired": "ACTIVE",
                "user_verification_status_desired": "NONE",
                "action_required": "NONE",
                "waiting_type": "AUTOMATED"
            }
        }
    ],
    "Pagination": {
        "future_url": "/v1/user/3576405/user-onboarding?newer_id=640514",
        "newer_url": null,
        "older_url": null
    }
}
```

Now the provisioned user has an Onboarding model which can be updated to be completed.

## Step 2: Update Onboarding model

The response to this endpoint gives you all the information you have to provide to have a verified and active user. All the fulfillments should be completed before the user is fully verified and can create Monetary Accounts, Cards, Payments etc.

**Endpoint:**

```http
PUT /v1/user/{user_id}/user-onboarding/{user_onboarding_id}
```

**Request body:**

```json
{
    "user_status_desired": "ACTIVE",
    "user_verification_status_desired": "VERIFIED"
}
```

**Response:**

```json
{
    "Error": [
        {
            "error_description": "You need to provide additional information in order to perform this action.",
            "error_description_translated": "You need to provide additional information in order to perform this action.",
            "error_additional_parameter": [
                {
                    "AdditionalFulfillmentParameter": {
                        "all_fulfillment": [
                            {
                                "type": "NAME",
                                "reason": "Let's make this account truly yours.",
                                "reason_translated": "Let's make this account truly yours.",
                                "user_id": 3565355,
                                "status": null,
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED"
                                ],
                                "id": null,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            },
                            {
                                "type": "DATE_OF_BIRTH",
                                "reason": "Let's make this account truly yours.",
                                "reason_translated": "Let's make this account truly yours.",
                                "user_id": 3565355,
                                "status": null,
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED"
                                ],
                                "id": null,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            },
                            {
                                "type": "ADDRESS_MAIN",
                                "reason": "",
                                "reason_translated": "",
                                "user_id": 3565355,
                                "status": null,
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED"
                                ],
                                "id": null,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            },
                            {
                                "type": "ADDRESS_POSTAL",
                                "reason": "So we know where to send your card.",
                                "reason_translated": "So we know where to send your card.",
                                "user_id": 3565355,
                                "status": null,
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED"
                                ],
                                "id": null,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            },
                            {
                                "type": "IDENTIFICATION_VERIFICATION",
                                "reason": "It takes just a few seconds to take a picture and complete your account.",
                                "reason_translated": "It takes just a few seconds to take a picture and complete your account.",
                                "user_id": 3565355,
                                "status": null,
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED",
                                    "IN_PROGRESS"
                                ],
                                "id": null,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            }
                        ],
                        "all_fulfillment_fulfilled": [
                            {
                                "type": "TERMS_OF_SERVICE",
                                "reason": "To continue using bunq without any hassle, please review and accept our updated Terms and Conditions.",
                                "reason_translated": "To continue using bunq without any hassle, please review and accept our updated Terms and Conditions.",
                                "user_id": 3565355,
                                "status": "FULFILLED",
                                "time_mandatory": null,
                                "all_status_allowed": [
                                    "FULFILLED"
                                ],
                                "id": 31574581,
                                "created_timestamp": null,
                                "updated_timestamp": null
                            }
                        ]
                    }
                }
            ]
        }
    ]
}
```

The Response body below is an example. For the `user_verification_status_desired` that was used in the POST call, the system will respond with the fulfillments that are required to be completed before the user is fully verified.