# Create an attendance period.

Create an attendance period and return newly created attendance period ID.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Attendances API",
    "version": "2.0.0",
    "description": "Endpoints to manage attendance periods, projects and their members."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Attendances",
      "description": "Endpoints relating to the times that people work, and the rules that define this."
    }
  ],
  "paths": {
    "/v2/attendance-periods": {
      "post": {
        "parameters": [
          {
            "$ref": "#/components/parameters/skipApprovalQueryParam"
          }
        ],
        "x-path-examples": {
          "201 POST Valid request": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "400 Invalid JSON": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "400 Invalid type field": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "400 Missing required parameters": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "403 Forbidden response": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "422 Start date greater than end date": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "422 Period time range too long": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          },
          "422 Break periods with project": {
            "value": "/papi/v2/attendance-periods",
            "query": "skip_approval=false"
          }
        },
        "tags": [
          "Attendances"
        ],
        "summary": "Create an attendance period.",
        "description": "Create an attendance period and return newly created attendance period ID.",
        "requestBody": {
          "$ref": "#/components/requestBodies/CreateAttendancePeriodRequest"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/AttendancePeriodCreatedResponse"
          },
          "400": {
            "$ref": "#/components/responses/AttendancePeriodBadRequestErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "422": {
            "$ref": "#/components/responses/AttendancePeriodUnprocessableContentErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "skipApprovalQueryParam": {
        "name": "skip_approval",
        "in": "query",
        "description": "If true, skip any approval that this write request would otherwise require.",
        "required": false,
        "schema": {
          "type": "boolean",
          "default": false,
          "example": false
        }
      }
    },
    "requestBodies": {
      "CreateAttendancePeriodRequest": {
        "description": "Request object for creating new attendance period.",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "person",
                "type",
                "start"
              ],
              "properties": {
                "person": {
                  "description": "Person reference by object ID",
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    }
                  }
                },
                "type": {
                  "description": "Required valid attendance period type.",
                  "type": "string",
                  "enum": [
                    "WORK",
                    "BREAK"
                  ]
                },
                "start": {
                  "description": "Date time property.",
                  "required": [
                    "date_time"
                  ],
                  "type": "object",
                  "properties": {
                    "date_time": {
                      "$ref": "#/components/schemas/DateTimeWithoutTimezone"
                    }
                  }
                },
                "end": {
                  "description": "Date time property.",
                  "type": "object",
                  "nullable": true,
                  "required": [
                    "date_time"
                  ],
                  "properties": {
                    "date_time": {
                      "$ref": "#/components/schemas/DateTimeWithoutTimezone"
                    }
                  }
                },
                "comment": {
                  "description": "Optional comment to associate with attendance period",
                  "type": "string"
                },
                "project": {
                  "description": "Project reference by object ID. Projects need to have status=ACTIVE. Periods with type=BREAK can't have a project.",
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "examples": {
              "201 POST Valid request": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "WORK",
                  "start": {
                    "date_time": "2024-01-01T10:00:00"
                  },
                  "end": {
                    "date_time": "2024-01-01T12:00:00"
                  },
                  "comment": "Some comment",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "400 Invalid JSON": {
                "value": {
                  "random": "INVALID JSON"
                }
              },
              "400 Invalid type field": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "OTHER",
                  "start": {
                    "date_time": "2024-01-01T10:00:00"
                  },
                  "end": {
                    "date_time": "2024-01-01T12:00:00"
                  },
                  "comment": "",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "400 Missing required parameters": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "WORK",
                  "comment": "",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "403 Forbidden response": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "WORK",
                  "start": {
                    "date_time": "2024-01-01T10:00:00"
                  },
                  "end": {
                    "date_time": "2024-01-01T12:00:00"
                  },
                  "comment": "Some comment",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "422 Start date greater than end date": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "WORK",
                  "start": {
                    "date_time": "2024-01-01T14:00:00"
                  },
                  "end": {
                    "date_time": "2024-01-01T12:00:00"
                  },
                  "comment": "Some comment",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "422 Period time range too long": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "WORK",
                  "start": {
                    "date_time": "2024-01-01T10:00:00"
                  },
                  "end": {
                    "date_time": "2024-01-02T11:00:00"
                  },
                  "comment": "",
                  "project": {
                    "id": "1"
                  }
                }
              },
              "422 Break periods with project": {
                "value": {
                  "person": {
                    "id": "1"
                  },
                  "type": "BREAK",
                  "start": {
                    "date_time": "2024-01-01T11:30:00"
                  },
                  "end": {
                    "date_time": "2024-01-01T12:30:00"
                  },
                  "project": {
                    "id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "AttendancePeriod": {
        "type": "object",
        "description": "- Model of period entity. - Describes a period of work or break time associated with a person.",
        "properties": {
          "id": {
            "type": "string",
            "example": "1234"
          },
          "person": {
            "type": "object",
            "description": "An object reference for a Person.",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "example": "1234"
              }
            }
          },
          "type": {
            "description": "Field definition of attendance period types.",
            "type": "string",
            "enum": [
              "WORK",
              "BREAK"
            ]
          },
          "is_auto_generated": {
            "description": "Only applies to break periods. Auto generated periods are created by the system based on customer configured break rules.",
            "type": "boolean"
          },
          "approval": {
            "type": "object",
            "description": "An object reference for approval details.",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "description": "Field definition of attendance period status.",
                "type": "string",
                "enum": [
                  "PENDING",
                  "CONFIRMED",
                  "REJECTED"
                ]
              }
            }
          },
          "start": {
            "description": "Date time property",
            "type": "object",
            "required": [
              "date_time"
            ],
            "properties": {
              "date_time": {
                "$ref": "#/components/schemas/DateTimeWithoutTimezone"
              }
            }
          },
          "end": {
            "description": "Date time property",
            "type": "object",
            "nullable": true,
            "required": [
              "date_time"
            ],
            "properties": {
              "date_time": {
                "$ref": "#/components/schemas/DateTimeWithoutTimezone"
              }
            }
          },
          "attribution_date": {
            "description": "The date that the work/break hours of this period are attributed to. This date can be different than both the date of the start and end time of this period, e.g. on overnight shifts.",
            "type": "string",
            "format": "date",
            "example": "2022-01-02"
          },
          "created_at": {
            "description": "Date time property",
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "description": "Date time property",
            "type": "string",
            "format": "date-time"
          },
          "comment": {
            "type": "string",
            "nullable": true,
            "maxLength": 1000,
            "example": "An example comment."
          },
          "project": {
            "nullable": true,
            "description": "Project object reference by ID.",
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "example": "1234"
              }
            }
          }
        }
      },
      "DateTimeWithoutTimezone": {
        "type": "string",
        "example": "2022-01-01T14:00:00",
        "description": "An RFC3339 date and timestamp without a timezone offset."
      }
    },
    "responses": {
      "ForbiddenResponse": {
        "description": "Forbidden",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "403 Forbidden response": {
                "$ref": "#/components/examples/ForbiddenResponse"
              }
            }
          }
        }
      },
      "NotFoundResponse": {
        "description": "The resource could not be found.",
        "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": {
              "404 Resource Not Found": {
                "$ref": "#/components/examples/NotFoundResponse"
              }
            }
          }
        }
      },
      "AttendancePeriodCreatedResponse": {
        "description": "Successful response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "affected_periods"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "id of the created or updated period, or id of the first created or updated period when more than one period is touched"
                },
                "affected_periods": {
                  "type": "array",
                  "description": "list of all created and updated periods as part of this call",
                  "items": {
                    "$ref": "#/components/schemas/AttendancePeriod"
                  }
                }
              }
            },
            "examples": {
              "201 POST Valid request": {
                "$ref": "#/components/examples/PostAttendancePeriodResponse"
              }
            }
          }
        }
      },
      "AttendancePeriodBadRequestErrorResponse": {
        "description": "Invalid request.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "400 Invalid JSON": {
                "$ref": "#/components/examples/InvalidPostPayloadResponse"
              },
              "400 Invalid type field": {
                "$ref": "#/components/examples/InvalidTypePayloadResponse"
              },
              "400 Missing required parameters": {
                "$ref": "#/components/examples/MissingRequiredFieldsPayloadResponse"
              }
            }
          }
        }
      },
      "AttendancePeriodUnprocessableContentErrorResponse": {
        "description": "Unprocessable content.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/NotFoundResponse/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "422 Start date greater than end date": {
                "$ref": "#/components/examples/StartGreaterThanEndResponse"
              },
              "422 Period time range too long": {
                "$ref": "#/components/examples/TimeRangeTooLongResponse"
              },
              "422 Project not trackable": {
                "$ref": "#/components/examples/AttendancePeriodsProjectNotTrackable"
              },
              "422 Break periods with project": {
                "$ref": "#/components/examples/BreakPeriodsWithProject"
              }
            }
          }
        }
      }
    },
    "examples": {
      "PostAttendancePeriodResponse": {
        "value": {
          "id": "9b620908-8252-4dbb-b406-053a9b9d8e98",
          "affected_periods": [
            {
              "id": "bd242cd1-5116-41a0-99aa-c12af4837c81",
              "person": {
                "id": "1234"
              },
              "type": "WORK",
              "approval": {
                "status": "PENDING"
              },
              "start": {
                "date_time": "2024-01-01T10:00:00"
              },
              "end": {
                "date_time": "2024-01-01T12:00:00"
              },
              "attribution_date": "2024-01-01",
              "created_at": "2024-07-18T14:55:30Z",
              "updated_at": "2024-07-18T14:55:30Z",
              "comment": "Some comment.",
              "project": {
                "id": "82173"
              }
            }
          ]
        }
      },
      "ForbiddenResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Access denied",
              "detail": "Access denied to perform attendance period operations.",
              "type": "https://developer.personio.de/reference/errors#common.forbidden_response"
            }
          ]
        }
      },
      "InvalidPostPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Input must be valid JSON",
              "detail": "The provided input is not a JSON object."
            }
          ]
        }
      },
      "InvalidTypePayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid field value",
              "detail": "Invalid value for field: type. Supported values are [WORK, BREAK]"
            }
          ]
        }
      },
      "MissingRequiredFieldsPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Missing required fields",
              "detail": "The following required fields are missing: [start]",
              "_meta": {
                "field": "start"
              }
            }
          ]
        }
      },
      "StartGreaterThanEndResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid start date",
              "detail": "Start date cannot be greater than end date of an attendance period."
            }
          ]
        }
      },
      "TimeRangeTooLongResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2026-01-28T11:17:30Z",
          "errors": [
            {
              "title": "Unprocessable entity",
              "detail": "Period cannot be longer than 24 hours."
            }
          ]
        }
      },
      "AttendancePeriodsProjectNotTrackable": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid project parameter",
              "detail": "Project not trackable"
            }
          ]
        }
      },
      "BreakPeriodsWithProject": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid project parameter",
              "detail": "Break periods cannot have a project associated"
            }
          ]
        }
      }
    }
  }
}
```