# Update an Employment.

- This endpoint enables the update of an Employment resource.
- The endpoint requires the personio:persons:write scope.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Employment",
    "version": "2.0.1",
    "description": "This is a set of REST endpoints for writing Person & Employment entities."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v2/persons/{person_id}/employments/{employment_id}": {
      "patch": {
        "summary": "Update an Employment.",
        "description": "- This endpoint enables the update of an Employment resource.\n- The endpoint requires the personio:persons:write scope.\n",
        "tags": [
          "Employments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PersonId"
          },
          {
            "$ref": "#/components/parameters/EmploymentId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Employment"
              },
              "examples": {
                "Update an Employment": {
                  "$ref": "#/components/examples/ValidUpdateEmployment"
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Employment updated successfully.",
            "x-response-example": "Update an Employment"
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/ResourceNotFound"
          }
        },
        "x-path-examples": {
          "Update an Employment": {
            "value": "/v2/persons/12345/employments/e07c1bd7-a5ec-4657-867b-4dba7197ea95"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Employment": {
        "type": "object",
        "description": "An Employment resource.",
        "properties": {
          "supervisor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The unique identifier for the `supervisor`.",
                "nullable": false
              }
            },
            "required": [
              "id"
            ],
            "description": "The `supervisor` object.",
            "nullable": true
          },
          "office": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The unique identifier for the `office`.",
                "nullable": false
              }
            },
            "required": [
              "id"
            ],
            "description": "The `office` object.",
            "nullable": true
          },
          "org_units": {
            "description": "All Org Units, i.e. department and team, that are to be associated with the Employment.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrgUnit"
            },
            "nullable": true
          },
          "subcompany": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The unique identifier for the `subcompany`. Note: this field is present only to support the mapping between subcompanies and legal entities. It is not advised to rely on this field. The legal entities should be used instead.\n",
                "nullable": false
              }
            },
            "required": [
              "id"
            ],
            "nullable": true,
            "deprecated": true
          },
          "legal_entity": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The unique identifier for the legal entity.",
                "nullable": false
              }
            },
            "required": [
              "id"
            ],
            "nullable": true
          },
          "position": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "The title of the `position`.",
                "nullable": false
              }
            },
            "description": "The `position` object.",
            "required": [
              "title"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "ONBOARDING",
              "LEAVE"
            ],
            "description": "Status of employment.",
            "nullable": false
          },
          "employment_start_date": {
            "type": "string",
            "format": "date",
            "description": "When the employment contract starts.",
            "nullable": false
          },
          "type": {
            "type": "string",
            "enum": [
              "INTERNAL",
              "EXTERNAL"
            ],
            "description": "The type of employment.",
            "nullable": false
          },
          "contract_end_date": {
            "type": "string",
            "format": "date",
            "description": "When the employment contract ends, if the contract is for temporary employment.",
            "nullable": true
          },
          "probation_end_date": {
            "type": "string",
            "format": "date",
            "description": "When the probation period ends. Only one of probation_period_length or probation_end_date should be set.",
            "nullable": true
          },
          "probation_period_length": {
            "type": "integer",
            "description": "Only one of probation_period_length or probation_end_date should be set.",
            "nullable": true
          },
          "weekly_working_hours": {
            "type": "number",
            "format": "float",
            "multipleOf": 0.01,
            "description": "The number of hours worked weekly.",
            "nullable": true
          },
          "full_time_weekly_working_hours": {
            "type": "number",
            "description": "The number of hours per week that is considered full time for the employment.",
            "format": "float",
            "multipleOf": 0.01,
            "nullable": true
          },
          "cost_centers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CostCenter"
            },
            "description": "The weight distribution of this employment between different cost centers, using percentages.",
            "nullable": false
          }
        }
      },
      "OrgUnit": {
        "description": "The Org Unit schema",
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of the Org Unit, e.g. team or department, to be associated with the Employment.",
            "nullable": false
          },
          "id": {
            "type": "string",
            "description": "The Internal ID of the Org Unit to be associated with the Employment.",
            "nullable": false
          }
        },
        "required": [
          "type",
          "id"
        ]
      },
      "CostCenter": {
        "type": "object",
        "description": "A weight assigned to a Cost Center resource.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique identifier of the Cost Center.",
            "nullable": false
          },
          "weight": {
            "type": "integer",
            "description": "The weight in percentage assigned to this Cost Center. The total of all Cost Center weights must be 100.",
            "nullable": false
          }
        },
        "required": [
          "id",
          "weight"
        ]
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "Invalid input data.",
        "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": {
              "Invalid parameter": {
                "$ref": "#/components/examples/InvalidParameter"
              }
            }
          }
        }
      },
      "ResourceNotFound": {
        "description": "Resource not found.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/InvalidRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Invalid parameter": {
                "$ref": "#/components/examples/ResourceNotFound"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "PersonId": {
        "name": "person_id",
        "in": "path",
        "description": "The ID of the target Person.",
        "example": "5678",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "EmploymentId": {
        "name": "employment_id",
        "in": "path",
        "description": "The ID of the target Employment.",
        "example": "493eff0a-2c5a-467e-8966-f70b4e3805a6",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "examples": {
      "ValidUpdateEmployment": {
        "value": {
          "supervisor": {
            "id": "4223"
          },
          "office": {
            "id": "231"
          },
          "org_units": [
            {
              "type": "team",
              "id": "523"
            },
            {
              "type": "department",
              "id": "943"
            }
          ],
          "position": {
            "title": "Senior Account Manager"
          },
          "legal_entity": {
            "id": "465"
          },
          "status": "ACTIVE",
          "employment_start_date": "2024-01-01",
          "type": "INTERNAL",
          "contract_end_date": "2024-12-31",
          "probation_end_date": "2024-03-31",
          "weekly_working_hours": 37.5,
          "cost_centers": [
            {
              "id": "653",
              "weight": 100
            }
          ]
        }
      },
      "InvalidParameter": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Bad request",
              "detail": "Provided request parameters are invalid.",
              "type": "https://developer.personio.de/reference/errors#common.bad_request"
            }
          ]
        }
      },
      "ResourceNotFound": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Resource not found",
              "detail": "No resource was found for the specified id.",
              "type": "https://developer.personio.de/reference/errors#common.resource_not_found"
            }
          ]
        }
      }
    }
  }
}
```