---
title: "Create a new entitlement registration line"
method: POST
path: "/public/registrations/v1/register-entitlement"
tags: ["Registration"]
---

# Create a new entitlement registration line

`POST /public/registrations/v1/register-entitlement`

## 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-entitlement`
- 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-entitlement/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new entitlement registration line with an optional file attachment.

**Attachment Rules:**
- Whether an attachment is required or not allowed is determined by the entitlement configuration.
- entitlements API can be used to fetch the entitlement configuration, which includes whether an attachment is required or not allowed for a specific entitlement.
- If an attachment is required but not provided, the request will be rejected with a 400 error.
- If an attachment is provided when not configured in entitlement, the document will still be stored
- Supported file types for attachments are PDF, PNG and JPEG. If the provided file is not one of these types, the request will be rejected with a 400 error.

## Request body `multipart/form-data`

- object
  - `request` EntitlementRegistrationRequestV1, required: Request body for creating an entitlement registration line
    - `placementId` string, uuid, required: The UUID of the placement for which the entitlement is being registered.
    - `projectId` string, uuid: Optional project ID
    - `entitlementId` string, uuid, required: The UUID of the entitlement. The list of registrable entitlements for a placement can be fetched from entitlements API
    - `amountInEuros` number: The registration amount in euros (€), Only used when the entitlement is not fixed-amount based. If the entitlement is fixed-amount based, this value will be ignored and the value stored while creating the entitlement wil be used
    - `date` string, date, required: The date on which the entitlement took place. Format: ISO 8601 (YYYY-MM-DD)
    - `description` string: Optional description or comment about this registration
  - `attachment` string, binary, nullable: PDF or image file attachment (receipt, invoice, etc.). Whether required or not is determined by the entitlement configuration.

## Response `200`

Entitlement registration line created successfully

- EntitlementRegistrationResponseV1: Response after saving an entitlement registration line
  - `registrationId` string, uuid, required: The ID of the created entitlement registration line
  - `attachmentFileId` string, uuid: The ID of the uploaded attachment file. Null if no attachment was uploaded.

## 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. * The entitlement requires an attachment but none was provided.
- `401`: The request did not contain credentials identifying the caller, or the provided credentials were invalid.
- `403`: The caller does not have permission to perform this action. This could be due to: * Lacking permission to access the placement's company or worker. * The company or worker being blacklisted for time writing.

## Changes

- **2026-09-29** `f9510f3f4b22`: 6 breaking, 7 info
  - added the new required request property `request/allOf[#/components/schemas/EntitlementRegistrationRequestV1]/date`
  - added the new required request property `request/allOf[#/components/schemas/EntitlementRegistrationRequestV1]/entitlementId`
  - added the new required request property `request/allOf[#/components/schemas/EntitlementRegistrationRequestV1]/placementId`
  - the `request/allOf[#/components/schemas/EntitlementRegistrationRequestV1]/` request property type changed from no type to `object`
  - …9 more
- **2026-09-29** `3352b56bb8fe`: 5 breaking, 7 warning, 1 info
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `object` to no type for status `400`
  - removed the required property `error` from the response with the `400` status
  - removed the required property `message` from the response with the `400` status
  - …9 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/registrations/v1/register-entitlement/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)