# Create Compensation. **Requires credential with both `personio:compensations:read` and `personio:compensations:write` scopes.** Creates a compensation for people for an authorized company. Compensation types supported include one time, recurring, fixed, and hourly. Bonuses are not supported. # 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 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 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" } } } } } } }, "post": { "summary": "Create Compensation.", "tags": [ "Compensations" ], "description": "**Requires credential with both `personio:compensations:read` and `personio:compensations:write` scopes.**\n\nCreates a compensation for people for an authorized company. Compensation types supported include one time, recurring, fixed, and hourly. Bonuses are not supported.\n", "x-path-examples": { "200 - Create Compensation": { "$ref": "#/components/examples/CreateCompensationRequest" }, "400 - Payload contains null values": { "$ref": "#/components/examples/CreateCompensationRequiredParamsMissingRequest" }, "400 - Payload contains invalid interval values": { "$ref": "#/components/examples/CreateCompensationInvalidIntervalRequest" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompensation" }, "examples": { "200 - Create Compensation": { "$ref": "#/components/examples/CreateCompensationRequest" } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateCompensation" }, { "type": "object", "properties": { "_meta": { "$ref": "#/paths/~1v2~1compensations/get/responses/200/content/application~1json/schema/properties/_meta" } } } ] }, "examples": { "200 - Create Compensation": { "$ref": "#/components/examples/CreateCompensationResponse" } } } } }, "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%2Bjson/schema" }, "examples": { "400 - Payload contains null values": { "$ref": "#/components/examples/CreateCompensationRequiredParamsMissingResponse" }, "400 - Payload contains invalid interval values": { "$ref": "#/components/examples/CreateCompensationInvalidIntervalResponse" } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "CreateCompensation": { "description": "Compensation Type creation schema payload.", "type": "object", "required": [ "person", "type", "value", "effective_from" ], "properties": { "person": { "type": "object", "properties": { "id": { "type": "string" } } }, "type": { "type": "object", "description": "The corresponding compensation. See [Compensation Types](https://developer.personio.de/reference/post_v2-compensations) for more details.\n", "properties": { "id": { "type": "string", "example": "9d23385b-a75d-4bdc-948d-808f7c5f098d" } } }, "value": { "type": "number", "format": "float", "description": "The amount of money in the currencies numeric unit, with up to two decimal places. For example, in case currency is EUR: * 20.50 - Twenty Euro and Fifty cents\n", "example": 20.5 }, "currency": { "$ref": "#/components/schemas/Currency" }, "effective_from": { "type": "string", "description": "The effective start date of the compensation.", "example": "2022-10-30" }, "interval": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "HALF-YEARLY", "YEARLY" ], "description": "The payout interval of the compensation. This field is mandatory for RECURRING compensations, if none is provided MONTHLY will be used by default. This field is ignored for ONE_TIME compensations. If the interval is YEARLY, the payout month will be the same as the one specified in the from field.\n" }, "comment": { "type": "string", "description": "An optional comment about this compensation.", "example": "A comment about this compensation" } } }, "Currency": { "description": "Supported currency following the _ISO-4217_ standard.", "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW" ] } }, "examples": { "CreateCompensationRequest": { "value": { "person": { "id": "1" }, "type": { "id": "12e21d39-58f3-4acb-b5ba-9b5ae228ea51" }, "value": 2500.5, "effective_from": "2022-10-15", "interval": "MONTHLY", "currency": "EUR" } }, "CreateCompensationRequiredParamsMissingRequest": { "value": { "person": { "id": "1" }, "type": { "id": "12e21d39-58f3-4acb-b5ba-9b5ae228ea51" }, "value": null, "effective_from": null } }, "CreateCompensationInvalidIntervalRequest": { "value": { "person": { "id": "1" }, "type": { "id": "12e21d39-58f3-4acb-b5ba-9b5ae228ea51" }, "value": 2500.5, "effective_from": "2022-10-15", "interval": "invalid" } }, "CreateCompensationResponse": { "value": { "id": "d9a7dc8c-d8f0-4b4f-b3ae-88f91db98c6a", "person": { "id": "1" }, "effective_from": "2022-10-15", "value": 2500.5, "type": { "id": "12e21d39-58f3-4acb-b5ba-9b5ae228ea51" }, "interval": "MONTHLY", "currency": "EUR" } }, "CreateCompensationRequiredParamsMissingResponse": { "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" } ] } }, "CreateCompensationInvalidIntervalResponse": { "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" } ] } } } } } ```