# Applying for the government bonus

## Government bonus overview

Eligible individuals can receive various types of government bonuses into their pension accounts. Before they can begin receiving these bonuses, users must first submit a bonus application (*Antrag auf Altersvorsorgezulage*) - either directly or via their provider - to the Zentrale Zulagenstelle für Altersvermögen (*ZfA*).

Once the ZfA approves the application, the user will automatically receive their eligible bonuses into their account during the ZfA’s defined distribution periods. Upvest can manage the application process on behalf of clients when permissions are granted and the relevant application details are submitted.

## Bonus application (*Grundzulage*)

Before submitting the bonus application, the user must grant permission to apply for the bonus on their behalf. The permission can be provided as recurring permission which is set once and valid until revoked, or one which must be renewed annually.

In the permission, the user must also state their eligibility for bonus payments. There are two types of eligibility based on the user’s situation:

- **Directly eligible:** the user meets the requirements to apply for bonus payments and is part of one of the following specific eligible groups:
  - Individuals in the Statutory Pension Insurance (*Deutsche Rentenversicherung*).
  - Self-employed individuals who are not part of the statutory pension insurance
  - Members of Professional Pension Schemes (*berufsständische Versorgungseinrichtung*)
  - Cross-border commuters (*Grenzgänger*): Persons who are compulsory members of a foreign statutory pension system and have unlimited tax liability in Germany - provided that the foreign compulsory membership is comparable to the domestic one.
  - Others such as civil servants, members of the agricultural pension fund or individuals on parental leave (*Kindererziehende*).
- **Indirectly eligible:** - the pension’s owner is not eligible but has an eligible spouse which makes them indirectly eligible to apply for the bonus.


## Child bonus application (*Kinderzulage*)

To receive the child bonus for a pension account, each child must be added to the permission entity. The child entry can be revoked at a future date if needed.

By default, the child bonus is disbursed to the parent actively receiving the Child Benefit (*Kindergeld*) for the specified period. To bypass this default and transfer the bonus to the other parent, the spouse's details must be added in the permissions to validate the transfer claim.

## Young adult bonus application (*Berufseinsteigerbonus*)

No additional information is required in the application to claim this bonus.

## Client application steps

The bonus application process encompasses two main steps:

1. Client: Storing the bonus application permissions for the owner of the pension account.
2. Client: Adding information on users included in the application, such as their spouse and children.


Once the steps are completed, Upvest processes the application and shares the application’s progress with the client.

You can use the `/bonus_permissions` endpoint to store the details of the provided permission including the type of permission and the start date when the permission was provided. Once this information is added, it can be referenced for all future applications until the details are revoked. Eligibility is also updated here.

Permission is linked to the pension account, if the user has two pension accounts they will need to apply a permission to each account they wish to make an application for bonuses from.

### 1. Bonus application permissions for the pension owner

For pension owners, all mandatory fields in `/users` must be filled out, along with the fields that were optional during onboarding. For more details, see the [Onboarding: Creating new and updating existing users](/products/byol/guides/tax_wrappers/german_pensions_implementing#1-onboarding-creating-new-and-updating-existing-users) section in this guide.

#### Example request adding details for the pension owner

**`POST /de_pension/wrappers/{wrapper_id}/bonus_permissions`**

Request

```json
{
 "qualifying_user": "PENSION_OWNER",
 "permission_type": "RECURRING",
 "eligibility_type": "DIRECTLY_ELIGIBLE",
 "valid_from": "2025-07-21T14:10:00.00Z",
 "valid_to": ""
}
```

Response

```json
{
  "permission_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa",
  "created_at": "2025-07-21T14:10:00.00Z",
  "updated_at": "2025-07-21T14:10:00.00Z",   
  "qualifying_user": "PENSION_OWNER",
  "permission_type": "RECURRING",
  "eligibility_type": "DIRECTLY_ELIGIBLE", 
  "valid_from": "2025-07-21T14:10:00.00Z",
  "valid_to": "",
  "status": "ACTIVE"
}
```

See the [Request fields for the `/bonus_permissions` endpoint](#request-fields-for-the-permissions-endpoint) section for details on each field.

### 2. Adding additional users’ details to the permission

Within the bonus permission entity, you can also enter additional application details for associated individuals by setting the `qualifying_user` field to `SPOUSE` or `CHILD`.

The `permission_type` field is not required for these users, permission is automatically recurring until revoked.

#### Example adding details of children for the child bonus

**`POST /de_pension/wrappers/{wrapper_id}/bonus_permissions`**

Request

```json
{
  "qualifying_user": "CHILD", 
  "valid_from": "2025-07-21T14:10:00.00Z",
  "first_name": "Fred",
  "last_name": "Schmidt",
  "birth_date":"2021-05-01",
  "bonus_transfer_consent":"0",
  "child_benefit_number":"123FK678901",
  "tax_identifier_number":"12345678901"
  }
```

See the [Request fields for the `/bonus_permissions` endpoint](#request-fields-for-the-permissions-endpoint) section for details on each field.

#### Example adding details for a spouse

A spouse can be added, if the pension owner is ineligible to apply, or if the spouse grants permission for a child bonus transfer.

**`POST /de_pension/wrappers/{wrapper_id}/bonus_permissions`**

Request

```json
{
  "qualifying_user": "SPOUSE", 
  "valid_from": "2024-07-21T14:10:00.00Z",
  "title":"DR",
  "first_name": "Kate",
  "last_name": "Schmidt",
  "gender": "FEMALE",
  "birth_city":"Berlin",
  "birth_date":"1983-05-01",
  "tax_identifier_number":"12345678901",
  "social_security_number":  "25300972S014"
}
```

See the [Request fields for the `/bonus_permissions` endpoint](#request-fields-for-the-permissions-endpoint) section for details on each field.

### Request fields for the permissions endpoint

| **Field** | **REQUIRED** | **Description** |
|  --- | --- | --- |
| `qualifying_user` | `All applicants` | The type of user being added to the bonus application. This field accepts the following values:  -   `PENSION_OWNER`: the main applicant and owner of the pension account. -   `SPOUSE`: the life partner to be included in the application. -   `CHILD`: an eligible child to be included in the application. |
| `permission_type` | `Pension owner only` | The type of permission being granted.  -   `RECURRING`: the user has granted a recurring permission (*Dauerzulagenantrag*) to apply for the government bonus until the permission is revoked. -   `ANNUAL`: the user has granted temporary permission which must be renewed each year.  You must set the `valid_to` field when `permission_type` equals `ANNUAL`. |
| `eligibility_type` | `Pension owner only` | The type of eligibility for the user.   -   `DIRECTLY_ELIGIBLE`: the user is eligible for the bonus payments. The user’s social security number must be available for the user. -   `CIVIL_SERVANT`: the user qualifies for bonus payments as a civil servant. -   `AGRICULTURAL_SCHEME_MEMBER`: the user qualifies for bonus payments as part of the agricultural pension fund.- `PARENTAL_LEAVE`:  the user is on leave without pay but can claim child-raising periods (*Kindererziehungszeiten*) if they are subject to mandatory insurance.  -   `INDIRECTLY_ELIGIBLE`: the user is not directly eligible but will provide details of a spouse who has eligibility. **Note**: When set to `INDIRECTLY_ELIGIBLE`, the details of the eligible spouse must be added to the bonus permission as shown below. |
| `valid_from` | `All applicants` | The start date when the permission was granted. |
| `valid_to` | `All applicants` | The end date for the granted permission, or date of revoked permission.Required when `permission_type` equals `ANNUAL`. |
| **Fields for additional users** |  | For spouses and children, use the `/bonus_permissions` endpoint fields below to add their user details.  Use the `/bonus_permissions` endpoint to set the pension owner's `bonus_transfer_consent`, if applicable. **Note**: For pension owners, user details can be added using the `/users` endpoint when onboarding a new user or updating an existing one. |
| `title` | `Optional` | The user’s title. You can use one of the following values:-   (empty string) -   `DR`: Doctor. -   `PROF`: Professor -   `PROF_DR`: PHD/Professor and Doctor -   `DIPL_ING`: Graduate engineer (Diplom-Indenieur) -   `MAGISTER`: Master of arts |
| `first_name` | `Required: Spouse and children` | The user’s first name. |
| `last_name` | `Required: Spouse and children` | The user’s family name. |
| `birth_date` | `Required: Spouse and children` | The user’s birth date. |
| `gender` | `Required: Spouse only` | The spouse’s gender. This field allows the following values:- `MALE`- `FEMALE`- `DIVERSE`- `UNKNOWN`**Note**: Gender is required for both the owner of the pension account and their spouse. However for the owner of the pension account, gender is added using the `/users` endpoint.Use the `/bonus_permissions` endpoint to list the gender for the spouse. |
| `birth_city` | `Required: Spouse only` | The city where the user was born. |
| `birth_name` | `Optional: Spouse only` | The user’s birth name. **Note**: You must add the optional **birth_name** field if the last name is different from the given birth name. |
| `bonus_transfer_consent` | `Optional: Child only` | Used when the pension’s owner wishes to transfer the child bonus payments to their spouse. -   **0**: The child bonus is not transferred and does not require consent for a transfer. -   **1**: Consent has been given to transfer the child bonus to a spouse. When set to **1**, the user must also provide the spouse’s details. |
| `tax_identifier_number` | `Required: Spouse and children` | The user’s tax identification number (TIN) |
| `child_benefit_number` | `Required: Child only` | The child’s assigned benefit number (*Kindergeldnummber*). |
| `social_security_number` | `Required: Spouse` | The spouse’s assigned social security number. If not provided, the ZfA will supply a `bonus_id`. |


If a `social_security_number` is not available, the ZfA will assign a `bonus_id`. This id will be updated to the bonus application when Upvest receives this value from the ZfA. If a `social_security_number` is provided in future, this number will be used in the application instead.

## Retrieving bonus permission details

You can retrieve the relevant details on a pension account and the  associated individuals by using a `GET` call. In the following example, the applicant is directly eligible and has added their child in order to apply for the child bonus.

#### Example retrieving permission details

**`GET /de_pension/wrappers/{wrapper_id}/bonus_permissions`**

Response

```json
{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 3,
    "total_count": 3,
    "sort": "qualifying_user",
    "order": "PRIORTIY"
  },
  "data": [ 
    {
      "permission_id": "019999a3-8a17-74e6-bfbd-50d9c7705ea0",  
      "user_id": "9d95820d-4333-46b6-98de-04ab7512e76f",
      "qualifying_user": "PENSION_OWNER",
      "permission_type": "RECURRING",
      "eligibility_type": "DIRECTLY_ELIGIBLE", 
      "valid_from": "2024-07-21T14:10:00.00Z" 
    },
    { 
       "permission_id": "019699a3-8a17-74e6-bfbd-60c4-7705ea5",
       "qualifying_user": "CHILD", 
       "valid_from": "2024-07-21T14:10:00.00Z",
       "title":"Mr",
       "first_name": "Fred",
       "last_name": "Schmidt",
       "birth_date":"1983-05-01",
       "tax_identifier_number":"12345678901",
       "child_benefit_number":"12345678901"
     }
    ]
   }
```

## Making changes to the permission

Permissions can be updated with new data or revoked at a later date if the application circumstances change using `PATCH`.  Updating a child or spouse status to `REVOKED` will remove them from the next bonus application.

#### Example retrieving permission details

**`PATCH /de_pension/wrappers/{wrapper_id}/bonus_permissions`**

Response

```json
{
  "permission_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb8aa",
  "valid_from": "2025-07-21T14:10:00.00Z",
  "valid_to": "2025-08-21T17:20:00.00", 
  "status": "REVOKED" 
}
```

## Completing the bonus application

The final step is for Upvest to submit the bonus application to the ZfA of all pension accounts with an `ACTIVE` bonus permission from the pension owner.  This is an annual process that is triggered using the `/bonus_applications` entity and can be tracked by clients using the `/bonus_applications` webhook and endpoint.

Upvest will:

* Stage 1: Create application


Prior to submitting to the ZfA, Upvest will create applications for all pension accounts with a valid permission from the pension owner for this year's submission. It will also collect data from all other permissions for spouse and children and flag any missing data needed for a successful submission. Every pension account will be assigned an application id with a status of `NEW`, `BONUS_APPLICATION_INCOMPLETE` or `READY_FOR_SUBMISSION`.

* Stage 2: Submit to ZfA


At a communicated cut off date, Upvest will send all pension accounts with `READY_FOR_SUBMISSION` to the ZfA. Statuses reflect whether the ZfA accepts the submission or not, with status `SUBMISSION_ACCEPTED` or `SUBMISSION_REJECTED`.  Where a submission is rejected Upvest will review if this due to a technical issue and resubmit. If the  issue is with the application itself (e.g., incorrect data), Upvest will coordinate with the client for fast resolution.

* Stage 3: Process ZfA response


Following the ZfA's review, the application status will be updated with the outcome of either `BONUS_APPLICATION_CONFIRMED` or `BONUS_APPLICATION_REJECTED` depending on the ZfA decision to award bonuses.

The bonus application goes through the following statuses:

| **Application stage** | **Status** | **Description** |
|  --- | --- | --- |
| Stage 1: Create application | `NEW` | The application has been created. |
| Stage 1: Create application | `BONUS_APPLICATION_INCOMPLETE` | The application is missing some of the required data. |
| Stage 1: Create application | `READY_FOR_SUBMISSION` | The minimum required information is available in the Upvest system and ready to send to the ZfA. |
| Stage 2: Submit to ZfA | `SUBMISSION_ACCEPTED` | The application has been sent and the ZfA has verified the information is correct. |
| Stage 2: Submit to ZfA | `SUBMISSION_REJECTED` | The submitted application was rejected by the ZfA. |
| Stage 3: Process ZfA response | `BONUS_APPLICATION_CONFIRMED` | The application was submitted and the bonus has been confirmed. |
| Stage 3: Process ZfA response | `BONUS_APPLICATION_REJECTED` | The application was submitted but the ZfA decided the user was not eligible for the bonus. |


The `/bonus_applications` endpoint can also be used to query historic applications. The entity will also be updated where the ZfA assigns a `bonus_id` (the ZfA will do this when a social security number is unavailable but the user is qualifying for a bonus).

#### Example retrieving bonus application history

**`GET /de_pension/wrappers/{tax_wrapper_id}/bonus_applications`**

Response

```json
{
 "meta": {
   "offset": 0,
   "limit": 100,
   "count": 2,
   "total_count": 2,
   "sort": "valid_from",
   "order": "DESC"
 },
 "data": [
   {
     "application_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4ab",
     "application_year": "2025",
     "submission_date": "2025-12-31T14:10:00.00",
	"identification": {
    "type": "SOCIAL_SECURITY_NUMBER",
    "id": "25300972S014"
    },
     "status": "BONUS_APPLICATION_CONFIRMED"
   },
   {
     "application_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa",
     "application_year": "2024",
     "submission_date": "2024-12-31T14:10:00.00",
     "identification": {
        "type": "BONUS_ID",
        "id": "40300972S345"
        },
     "status": "BONUS_APPLICATION_CONFIRMED"
   }
 ]
}
```