# Create a new Person and Employment.

- This endpoint enables the creation of a Person resource and an associated Employment resource.
- The endpoint requires the personio:persons:write scope.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Person",
    "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": {
      "post": {
        "summary": "Create a new Person and Employment.",
        "description": "- This endpoint enables the creation of a Person resource and an associated Employment resource.\n- The endpoint requires the personio:persons:write scope.\n",
        "tags": [
          "Persons"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePerson"
              },
              "examples": {
                "Create new Person": {
                  "$ref": "#/components/examples/ValidCreatePerson"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Person and Employment created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePersonResponse"
                },
                "examples": {
                  "Create new Person": {
                    "$ref": "#/components/examples/ValidCreatePersonResponse"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Person": {
        "type": "object",
        "description": "The Person model.",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email of the employee. The email must be unique : 2+ employees cannot have the same email.",
            "nullable": false
          },
          "first_name": {
            "type": "string",
            "description": "First name of the employee.",
            "nullable": false
          },
          "preferred_name": {
            "type": "string",
            "description": "The preferred name of the employee, if relevant.",
            "nullable": false
          },
          "last_name": {
            "type": "string",
            "description": "Last name of the employee.",
            "nullable": false
          },
          "gender": {
            "type": "string",
            "enum": [
              "MALE",
              "FEMALE",
              "DIVERSE",
              "UNKNOWN",
              "UNDEFINED"
            ],
            "description": "Gender of the employee.",
            "nullable": true
          },
          "language_code": {
            "type": "string",
            "enum": [
              "en",
              "de",
              "es",
              "fr",
              "nl",
              "it",
              "sv",
              "fi"
            ],
            "description": "Main language of the employee.",
            "nullable": false
          },
          "custom_attributes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The ID for the attribute.",
                  "nullable": false
                },
                "value": {
                  "oneOf": [
                    {
                      "type": "string",
                      "description": "An arbitrary value that can be represented as a string.",
                      "example": "Munich Center"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "An array of arbitrary values that can be represented as a string.",
                      "example": [
                        "Munich center",
                        "Munich train station"
                      ]
                    }
                  ],
                  "nullable": false
                }
              }
            },
            "description": "List of custom attributes for the employee."
          }
        }
      },
      "CreatePerson": {
        "description": "The payload for creating Person and Employment resources.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Person"
          },
          {
            "type": "object",
            "properties": {
              "employments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Employment"
                }
              }
            }
          },
          {
            "required": [
              "first_name",
              "last_name"
            ]
          }
        ]
      },
      "CreatePersonResponse": {
        "type": "object",
        "description": "The response object when creating a Person and Employment.",
        "properties": {
          "id": {
            "type": "string",
            "example": "some-random-id",
            "description": "The id of the created Person."
          },
          "employments": {
            "type": "array",
            "description": "A list of ids of created Employments.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "some-random-id",
                  "description": "The id of the created Employment."
                }
              }
            }
          },
          "_meta": {
            "type": "object",
            "properties": {
              "links": {
                "type": "object",
                "properties": {
                  "self": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://api.personio.de/v2/persons/some-person-id"
                  }
                }
              }
            }
          }
        }
      },
      "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"
              }
            }
          }
        }
      }
    },
    "examples": {
      "ValidCreatePerson": {
        "value": {
          "email": "john.smith@company.com",
          "first_name": "John",
          "preferred_name": "Dr. Smith",
          "last_name": "Smith",
          "gender": "MALE",
          "language_code": "de",
          "custom_attributes": [
            {
              "id": "laptop_serial_number",
              "value": "123-456"
            },
            {
              "id": "customer_offices",
              "value": [
                "Munich center",
                "Munich train station"
              ]
            }
          ],
          "employments": [
            {
              "supervisor": {
                "id": "4223"
              },
              "office": {
                "id": "231"
              },
              "org_units": [
                {
                  "type": "team",
                  "id": "523"
                },
                {
                  "type": "department",
                  "id": "943"
                }
              ],
              "legal_entity": {
                "id": "465"
              },
              "position": {
                "title": "Senior Account Manager"
              },
              "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
                }
              ]
            }
          ]
        }
      },
      "ValidCreatePersonResponse": {
        "value": {
          "id": "3003",
          "employments": [
            {
              "id": "c85d978e-1104-4762-be94-c868525eef45"
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/persons/3003"
              }
            }
          }
        }
      },
      "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"
            }
          ]
        }
      }
    }
  }
}
```