> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/people-absence-company-resource.md).

# People Absence Company Resource

## Correct an absence

> The employee is taken from the stored record; only the period and reason change.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PersonAbsenceUpsertRequest":{"type":"object","description":"Absence period to register or correct","properties":{"email":{"type":"string","description":"Employee e-mail. Give this or externalId when registering a new absence."},"externalId":{"type":"string","description":"Employee id in the company's own HR system. Give this or email when registering."},"from":{"type":"string","format":"date","description":"First day of the absence, inclusive"},"to":{"type":"string","format":"date","description":"Last day of the absence, inclusive. Omit while the employee is still on leave; on a\ncorrection, sending it closes an ongoing absence and omitting it reopens a closed one.\n"},"reason":{"$ref":"#/components/schemas/AbsenceReason"}},"required":["from","reason"]},"AbsenceReason":{"type":"string","description":"Reason for a period of absence: work accident or temporary disability","enum":["WORK_ACCIDENT","TEMPORARY_DISABILITY"]},"PersonAbsence":{"type":"object","description":"A period of absence of one employee","properties":{"id":{"type":"string","description":"Absence identifier (24-char hex)"},"email":{"type":"string","description":"Employee e-mail"},"name":{"type":"string","description":"Employee name"},"externalId":{"type":"string","description":"Employee id in the company's own HR system"},"from":{"type":"string","format":"date","description":"First day of the absence, inclusive"},"to":{"type":"string","format":"date","description":"Last day of the absence, inclusive. Null while the employee is still on leave."},"ongoing":{"type":"boolean","description":"True while the employee is still on leave, i.e. the absence has no end date yet"},"reason":{"$ref":"#/components/schemas/AbsenceReason"},"calendarDays":{"type":"integer","format":"int32","description":"Duration in calendar days, both ends inclusive. This is the figure filters use.\nFor an ongoing absence, the days elapsed up to today.\n"},"estimatedWorkingDays":{"type":"integer","format":"int32","description":"Duration in working days, derived from the employee's registered shift.\nNull when the employee has no shift registered. It is an estimate — no bank-holiday\ncalendar exists — and it is never used for filtering. Counted up to today while ongoing.\n"}}}}},"paths":{"/api/v1/company/absences/{absenceId}":{"put":{"tags":["people-absence-company-resource"],"summary":"Correct an absence","description":"The employee is taken from the stored record; only the period and reason change.","operationId":"update","parameters":[{"name":"absenceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonAbsenceUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PersonAbsence"}}}}}}}}}
```

## DELETE /api/v1/company/absences/{absenceId}

> Delete an absence

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/absences/{absenceId}":{"delete":{"tags":["people-absence-company-resource"],"summary":"Delete an absence","operationId":"delete","parameters":[{"name":"absenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}
```

## List absences overlapping a period

> A leave counts when it overlaps the window; it need not be contained in it.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"AbsenceReason":{"type":"string","description":"Reason for a period of absence: work accident or temporary disability","enum":["WORK_ACCIDENT","TEMPORARY_DISABILITY"]},"PersonAbsence":{"type":"object","description":"A period of absence of one employee","properties":{"id":{"type":"string","description":"Absence identifier (24-char hex)"},"email":{"type":"string","description":"Employee e-mail"},"name":{"type":"string","description":"Employee name"},"externalId":{"type":"string","description":"Employee id in the company's own HR system"},"from":{"type":"string","format":"date","description":"First day of the absence, inclusive"},"to":{"type":"string","format":"date","description":"Last day of the absence, inclusive. Null while the employee is still on leave."},"ongoing":{"type":"boolean","description":"True while the employee is still on leave, i.e. the absence has no end date yet"},"reason":{"$ref":"#/components/schemas/AbsenceReason"},"calendarDays":{"type":"integer","format":"int32","description":"Duration in calendar days, both ends inclusive. This is the figure filters use.\nFor an ongoing absence, the days elapsed up to today.\n"},"estimatedWorkingDays":{"type":"integer","format":"int32","description":"Duration in working days, derived from the employee's registered shift.\nNull when the employee has no shift registered. It is an estimate — no bank-holiday\ncalendar exists — and it is never used for filtering. Counted up to today while ongoing.\n"}}}}},"paths":{"/api/v1/company/absences":{"get":{"tags":["people-absence-company-resource"],"summary":"List absences overlapping a period","description":"A leave counts when it overlaps the window; it need not be contained in it.","operationId":"list","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"reasons","in":"query","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/AbsenceReason"},"uniqueItems":true}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PersonAbsence"}}}}}}}}}}
```

## POST /api/v1/company/absences

> Register a single absence

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PersonAbsenceUpsertRequest":{"type":"object","description":"Absence period to register or correct","properties":{"email":{"type":"string","description":"Employee e-mail. Give this or externalId when registering a new absence."},"externalId":{"type":"string","description":"Employee id in the company's own HR system. Give this or email when registering."},"from":{"type":"string","format":"date","description":"First day of the absence, inclusive"},"to":{"type":"string","format":"date","description":"Last day of the absence, inclusive. Omit while the employee is still on leave; on a\ncorrection, sending it closes an ongoing absence and omitting it reopens a closed one.\n"},"reason":{"$ref":"#/components/schemas/AbsenceReason"}},"required":["from","reason"]},"AbsenceReason":{"type":"string","description":"Reason for a period of absence: work accident or temporary disability","enum":["WORK_ACCIDENT","TEMPORARY_DISABILITY"]},"PersonAbsence":{"type":"object","description":"A period of absence of one employee","properties":{"id":{"type":"string","description":"Absence identifier (24-char hex)"},"email":{"type":"string","description":"Employee e-mail"},"name":{"type":"string","description":"Employee name"},"externalId":{"type":"string","description":"Employee id in the company's own HR system"},"from":{"type":"string","format":"date","description":"First day of the absence, inclusive"},"to":{"type":"string","format":"date","description":"Last day of the absence, inclusive. Null while the employee is still on leave."},"ongoing":{"type":"boolean","description":"True while the employee is still on leave, i.e. the absence has no end date yet"},"reason":{"$ref":"#/components/schemas/AbsenceReason"},"calendarDays":{"type":"integer","format":"int32","description":"Duration in calendar days, both ends inclusive. This is the figure filters use.\nFor an ongoing absence, the days elapsed up to today.\n"},"estimatedWorkingDays":{"type":"integer","format":"int32","description":"Duration in working days, derived from the employee's registered shift.\nNull when the employee has no shift registered. It is an estimate — no bank-holiday\ncalendar exists — and it is never used for filtering. Counted up to today while ongoing.\n"}}}}},"paths":{"/api/v1/company/absences":{"post":{"tags":["people-absence-company-resource"],"summary":"Register a single absence","operationId":"register_3","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonAbsenceUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PersonAbsence"}}}}}}}}}
```

## Upload a spreadsheet of absences

> Rows are processed independently: valid rows are stored even when others fail.\
> The response reports every row — accepted, already existing, or rejected with the\
> reason and its line number. A row identical to a stored absence is reported as\
> already existing rather than as an error, so a corrected file can be uploaded whole.<br>

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PeopleAbsenceUploadResult":{"type":"object","description":"Per-row outcome of an absence spreadsheet upload","properties":{"totalRows":{"type":"integer","format":"int32","description":"Data rows read from the file, excluding the header"},"accepted":{"type":"integer","format":"int32","description":"Rows stored by this upload"},"alreadyExisted":{"type":"integer","format":"int32","description":"Rows describing an absence that was already stored, identical in every field"},"closed":{"type":"integer","format":"int32","description":"Rows giving the end date of an absence stored as still ongoing, which is now closed"},"rejected":{"type":"integer","format":"int32","description":"Rows that could not be stored"},"rows":{"type":"array","description":"One entry per row, in file order","items":{"$ref":"#/components/schemas/PeopleAbsenceUploadRowResult"}}}},"PeopleAbsenceUploadRowResult":{"type":"object","description":"What happened to one row of the spreadsheet","properties":{"line":{"type":"integer","format":"int32","description":"1-based line number in the spreadsheet, matching what the user sees"},"outcome":{"$ref":"#/components/schemas/PeopleAbsenceUploadRowOutcome"},"error":{"type":"string","description":"Why the row was rejected. Null when it was not."},"employee":{"type":"string","description":"Employee identifier as written in the file, echoed back to locate the row"}}},"PeopleAbsenceUploadRowOutcome":{"type":"string","enum":["ACCEPTED","ALREADY_EXISTED","CLOSED","REJECTED"]}}},"paths":{"/api/v1/company/absences/upload":{"post":{"tags":["people-absence-company-resource"],"summary":"Upload a spreadsheet of absences","description":"Rows are processed independently: valid rows are stored even when others fail.\nThe response reports every row — accepted, already existing, or rejected with the\nreason and its line number. A row identical to a stored absence is reported as\nalready existing rather than as an error, so a corrected file can be uploaded whole.\n","operationId":"upload","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PeopleAbsenceUploadResult"}}}}}}}}}
```

## Download the absence upload template

> Empty xlsx with the expected columns and a dropdown of the accepted reasons.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/absences/template":{"get":{"tags":["people-absence-company-resource"],"summary":"Download the absence upload template","description":"Empty xlsx with the expected columns and a dropdown of the accepted reasons.","operationId":"downloadTemplate_1","responses":{"200":{"description":"OK","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}}}}}}}
```
