---
title: "Register kilometer allowance"
method: POST
path: "/public/registrations/v1/register-kilometer-allowance"
tags: ["Registration"]
---

# Register kilometer allowance

`POST /public/registrations/v1/register-kilometer-allowance`

## Request

- Base URL: `https://api.maqqie.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maqqie.app/public/registrations/v1/register-kilometer-allowance`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://maqqie.app/auth/realms/maqqie/protocol/openid-connect/token`
- TypeScript: <https://skmtc.dev/maqqie/apis/maqqie-public-api/docs/public/registrations/v1/register-kilometer-allowance/post.ts> (a function with typed inputs; its response is checked against the schema)

Registers the kilometer allowance for the worker. from and to address are optional. If they are not present, the
location of the placement and the home address of the worker will be used. The distance is as determined by the Mapbox API

## Request body

- KilometerAllowanceRegistrationRequestV1: If toAddress is empty, the address of the location of the placement will be used. If fromAddress is empty, the home address of the worker will be used.
  - `placementId` string, uuid, required: The UUID of the placement for which the kilometer allowance is being registered.
  - `projectId` string, uuid: The UUID of the project if the kilometer allowance is registered on a project.
  - `projectName` string: The name of the project if the hours are registered on a project. When a new project name is received, a project is automatically created. When a known project name is received, the existing project is used.
  - `date` string, date, required: The date of the trip. Format: ISO 8601 (YYYY-MM-DD)
  - `fromAddress` AddressDetailsV1: Address details.
    - `street` string, required: The street name of the address.
    - `houseNumber` integer, required: The house number of the address, excluding suffix. For a house number 123A, this would be 123.
    - `houseNumberAddition` string: House number suffix (if any). For a house number 123A, this would be 'A'.
    - `zipCode` string, required: The postal code of the address. Must be a post code that actually exists in the Netherlands.
    - `city` string, required: The city of the address.
    - `countryCode` string, required: The country code in ISO 3166-1 alpha-2 format.
  - `toAddress` AddressDetailsV1: Address details.
    - `street` string, required: The street name of the address.
    - `houseNumber` integer, required: The house number of the address, excluding suffix. For a house number 123A, this would be 123.
    - `houseNumberAddition` string: House number suffix (if any). For a house number 123A, this would be 'A'.
    - `zipCode` string, required: The postal code of the address. Must be a post code that actually exists in the Netherlands.
    - `city` string, required: The city of the address.
    - `countryCode` string, required: The country code in ISO 3166-1 alpha-2 format.

## Response `200`

Successfully registered kilometer allowance

- KilometerAllowanceRegistrationResponseV1
  - `registrationId` string, uuid
  - `kilometers` number, required: The total distance registered, in kilometers. This includes the return trip, if applicable.
  - `amount` number: The wage for the kilometers, in €.

## Other responses

- `400`: The request could not be processed. This could be due to a number of reasons: * The request does not have all required data. * Data in the request is invalid. * Data in the request is inconsistent. * The operation is not allowed given the current state of the data.
- `401`: The request did not contain credentials identifying the caller, or the provided credentials were invalid.
- `403`: The data that the request referred to is inaccessible to the caller.

## Changes

- **2026-09-29** `f9510f3f4b22`: 5 breaking, 7 info
  - added the new required request property `date`
  - added the new required request property `placementId`
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - …8 more
- **2026-09-29** `3352b56bb8fe`: 4 breaking, 8 warning, 7 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the required property `kilometers` from the response with the `200` status
  - …15 more
- **2026-09-16** `ccf9834e5006`: 5 breaking, 7 info
  - added the new required request property `date`
  - added the new required request property `placementId`
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - …8 more
- **2026-09-15** `8085d4c1ab80`: 4 breaking, 8 warning, 7 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the required property `kilometers` from the response with the `200` status
  - …15 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/registrations/v1/register-kilometer-allowance/post.md)

---

[API](https://skmtc.dev/maqqie/apis/maqqie-public-api.md) - [All operations](https://skmtc.dev/maqqie/apis/maqqie-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maqqie/apis/maqqie-public-api/revisions/13ed331da2b2?raw)