--- updatedAt: 2026-06-03T14:38:22.000Z agentTools: projectIndex: https://developer.personio.de/llms.txt --- # Create Compensation Types. Creates a new Compensation Type and returns the created resource with its UUID. This UUID can be used to create a new compensation. The types include one-time and recurring Compensation Types for salary workers. Hourly types are not supported and bonuses should use recurring or one time types. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Payroll Integrations API", "description": "Collection of endpoints that will allow external companies to integrate Payroll providers with Personio's.", "version": "2.0.0" }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/compensations": { "get": { "summary": "List compensations.", "tags": [ "Compensations" ], "description": "Returns a list of payroll compensations of people for an authorized company. Compensations listed include base salary (excluding proration), hourly, one time compensation, recurring compensation, and bonuses.\n", "parameters": [ { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "example": "2020-01-01", "description": "A start date from which compensations are run. The duration (end_date - start_date) must be equal to or smaller than a month. The format is ISO-8601. Default is the first day of the current month in case end_date is not provided, or the first day of the month of the provided end_date.\n" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "example": "2020-01-30", "description": "An end date to which compensations are run. The duration (end_date - start_date) must be equal or smaller than a month. Format is ISO-8601. Default is the last day of the current month in case start_date is not provided, or the last day of the month of the provided start_date.\n" }, { "in": "query", "name": "person.id", "schema": { "type": "string" }, "description": "Filter results matching one or more provided person ids that belong to the company.", "example": "1,2,3" }, { "in": "query", "name": "legal_entity.id", "schema": { "type": "string" }, "description": "Filter results matching one or more provided legal entity ids that belong to the company.", "example": "1,2,3" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 100 }, "example": 100, "description": "The amount of resources to be returned per one request. It can range between 1 and 100, and the default is 100." }, { "in": "query", "name": "cursor", "example": "cur_82sQwR2eZvKilo2duNh219Kw", "required": false, "schema": { "type": "string" }, "description": "The pagination cursor to navigate over to the next list of resources. If you pass a specific limit to your request, or you rely on the default value of the number of resources to be returned, then your subsequent call has to include the cursor in order to retrieve the next list of resources. If cursor is missing, the first page is returned." } ], "x-path-examples": { "200 - List all compensations": { "value": "/v2/compensations" }, "200 - List compensations filtered by a date range": { "value": "/v2/compensations", "query": "start_date=2020-01-01&end_date=2020-01-30" }, "200 - List compensations filtered by a single person.id": { "value": "/v2/compensations", "query": "person.id=100" }, "200 - List compensations filtered by multiple person.id": { "value": "/v2/compensations", "query": "person.id=100,200" }, "200 - List compensations filtered by multiple legal_entity.id": { "value": "/v2/compensations", "query": "legal_entity.id=1000,3000" }, "400 - List payroll with non allowed limit value": { "value": "/v2/compensations", "query": "limit=101" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/Compensation" } }, "_meta": { "description": "This object represents the metadata information for an object. It's a set of arbitrary key/value attributes such as `links`.", "type": "object", "readOnly": true, "properties": { "links": { "type": "object", "additionalProperties": { "description": "This objects represents a hyperlink.", "type": "object", "readOnly": true, "properties": { "href": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "example": { "links": { "self": { "href": "https://api.personio.de/v2/person?cursor=" } } } } } } } }, "examples": { "200 - List all compensations": { "value": { "_data": [ { "id": "1", "person": { "id": "100" }, "legal_entity": { "id": "1000" }, "type": { "name": "Fitnessstudiobeitrag", "category": "ONE_TIME" }, "amount": { "value": 3000, "currency": "EUR" }, "interval": "ONE_TIME", "effective_from": "2022-10-01", "weekly_working_hours": null, "full_time_weekly_working_hours": null }, { "id": "2", "person": { "id": "200" }, "legal_entity": { "id": "2000" }, "type": { "name": "Gehalt", "category": "FIXED_SALARY" }, "amount": { "value": 2000, "currency": "EUR" }, "interval": "MONTHLY", "effective_from": "2022-10-01", "weekly_working_hours": 40, "full_time_weekly_working_hours": 40 } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations" } } } } }, "200 - List compensations filtered by a date range": { "value": { "_data": [ { "id": "1", "person": { "id": "100" }, "legal_entity": { "id": "1000" }, "type": { "name": "Fitnessstudiobeitrag", "category": "ONE_TIME" }, "amount": { "value": 3000, "currency": "EUR" }, "interval": "ONE_TIME", "effective_from": "2020-01-15", "weekly_working_hours": null, "full_time_weekly_working_hours": null } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations" } } } } }, "200 - List compensations filtered by a single person.id": { "value": { "_data": [ { "id": "1", "person": { "id": "100" }, "legal_entity": { "id": "1000" }, "type": { "name": "Fitnessstudiobeitrag", "category": "ONE_TIME" }, "amount": { "value": 3000, "currency": "EUR" }, "interval": "ONE_TIME", "effective_from": "2022-10-01" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations" } } } } }, "200 - List compensations filtered by multiple person.id": { "value": { "_data": [ { "id": "1", "person": { "id": "100" }, "legal_entity": { "id": "1000" }, "type": { "name": "Fitnessstudiobeitrag", "category": "ONE_TIME" }, "amount": { "value": 3000, "currency": "EUR" }, "interval": "ONE_TIME", "effective_from": "2022-10-01", "weekly_working_hours": null, "full_time_weekly_working_hours": null }, { "id": "2", "person": { "id": "200" }, "legal_entity": { "id": "2000" }, "type": { "name": "Gehalt", "category": "FIXED_SALARY" }, "amount": { "value": 2000, "currency": "EUR" }, "interval": "MONTHLY", "effective_from": "2022-10-01", "weekly_working_hours": 40, "full_time_weekly_working_hours": 40 } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations" } } } } }, "200 - List compensations filtered by multiple legal_entity.id": { "value": { "_data": [ { "id": "1", "person": { "id": "100" }, "legal_entity": { "id": "1000" }, "type": { "name": "Fitnessstudiobeitrag", "category": "ONE_TIME" }, "amount": { "value": 3000, "currency": "EUR" }, "interval": "ONE_TIME", "effective_from": "2022-10-01", "weekly_working_hours": null, "full_time_weekly_working_hours": null } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations" } } } } } } } } }, "400": { "description": "The current request is invalid. Please make sure you pass all the required parameters and you are using the proper content-type.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "This object represents an error response.", "properties": { "personio_trace_id": { "type": "string", "example": "aswo3f-a202lfso-312123sld-1230ddd", "description": "A unique ID that was created for this error." }, "timestamp": { "type": "string", "format": "date-time", "example": "2021-05-28T11:17:30.000Z", "description": "The timestamp of when the error occurred." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Not found", "description": "The title of the error." }, "detail": { "type": "string", "example": "The requested resource was not found.", "description": "A short description about the error." }, "type": { "type": "string", "format": "uri", "example": "https://developer.personio.de/reference/errors#common.requested_resource_not_found", "description": "A link to the developer hub where more information can be found for the encountered error." }, "_meta": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "examples": { "400 - List payroll with non allowed limit value": { "$ref": "#/components/examples/InvalidLimitValue" } } } } } } } }, "/v2/compensations/types": { "post": { "summary": "Create Compensation Types.", "tags": [ "Compensations" ], "description": "Creates a new Compensation Type and returns the created resource with its UUID. This UUID can be used to create a new compensation. The types include one-time and recurring Compensation Types for salary workers. Hourly types are not supported and bonuses should use recurring or one time types.\n", "x-path-examples": { "Success - Create Value Compensation": { "$ref": "#/components/examples/CreateCompensationTypeRequest" }, "Bad request - Payload contains null values": { "$ref": "#/components/examples/CreateCompensationTypeRequiredParamsMissingRequest" }, "Bad request - Payload contains invalid type values": { "$ref": "#/components/examples/CreateCompensationTypeInvalidFrequencyRequest" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompensationType" }, "examples": { "Success - Create Value Compensation": { "$ref": "#/components/examples/CreateCompensationTypeRequest" } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CompensationType" }, { "type": "object", "properties": { "_meta": { "$ref": "#/paths/~1v2~1compensations/get/responses/200/content/application~1json/schema/properties/_meta" } } } ] }, "examples": { "Success - Create Value Compensation": { "$ref": "#/components/examples/CreateCompensationTypeResponse" } } } } }, "400": { "description": "The current request is invalid. Please make sure you pass all the required parameters and you are using the proper content-type.", "content": { "application/problem+json": { "schema": { "$ref": "#/paths/~1v2~1compensations/get/responses/400/content/application~1problem+json/schema" }, "examples": { "Bad request - Payload contains null values": { "$ref": "#/components/examples/CreateCompensationTypeRequiredParamsMissingResponse" }, "Bad request - Payload contains invalid type values": { "$ref": "#/components/examples/CreateCompensationTypeInvalidFieldResponse" } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "CompensationType": { "description": "Compensation Type schema.", "type": "object", "required": [ "id", "name", "category" ], "properties": { "id": { "type": "string", "description": "UUID of the Compensation Type." }, "name": { "type": "string", "description": "Name given to the Compensation Type." }, "category": { "type": "string", "enum": [ "FIXED_SALARY", "HOURLY_SALARY", "RECURRING", "ONE_TIME" ], "description": "Payout frequency of the compensations of this type. FIXED_SALARY is the usual monthly or yearly salary. HOURLY_SALARY is the rate of the hour. ONE_TIME or RECURRING are bonuses and extra payments." } } }, "CreateCompensationType": { "description": "Compensation Type creation schema payload.", "type": "object", "required": [ "name", "category" ], "properties": { "name": { "type": "string", "description": "Name of the Compensation Type.", "example": "Gym benefit" }, "category": { "type": "string", "enum": [ "RECURRING", "ONE_TIME" ], "description": "Payout frequency of the compensations of this type. ONE_TIME or RECURRING are bonuses and extra payments." } } } }, "examples": { "CreateCompensationTypeRequest": { "value": { "name": "Public Transport", "category": "RECURRING" } }, "CreateCompensationTypeResponse": { "value": { "id": "de49b0e6-c151-45f1-9211-34ff7dcb9e0a", "name": "Public Transport", "category": "RECURRING", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/compensations/types" } } } } }, "CreateCompensationTypeRequiredParamsMissingRequest": { "value": { "name": "Public Transport without type", "category": null } }, "CreateCompensationTypeRequiredParamsMissingResponse": { "value": { "personio_trace_id": "baaaaaad-c0de-fade-baad-c000000000de", "timestamp": "2023-03-01T14:07:17Z", "errors": [ { "title": "Bad Request", "detail": "The request has missing or invalid required parameters.", "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#compensations.invalid_request.required_parameters_missing" } ] } }, "CreateCompensationTypeInvalidFrequencyRequest": { "value": { "name": "Public Transport with invalid type", "category": "BONUS" } }, "CreateCompensationTypeInvalidFieldResponse": { "value": { "personio_trace_id": "baaaaaad-c0de-fade-baad-c000000000de", "timestamp": "2023-03-01T14:07:17Z", "errors": [ { "title": "Bad Request", "detail": "The request has invalid parameters.", "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#compensations.invalid_request.parameters_invalid" } ] } } } } } ```