Book an absence
POSThttps://
Books an absence for an employee and returns it with a Location header.
Access
- Token scope
- api:
write: absences Without it:
403 insufficient-token-scope. - Permission
- absences::
manage Without it:
403 insufficient-permission. - Rate cost
- 1 unit, write bucket. A write costs the same whatever
viewyou ask for. - Also
- Accepts
Idempotency-Key. Never cached:private, no-store. Unknown body keys are refused, never dropped.
Both are checked, scope first. A token never does more than its user. How access is checked
start and end are stored exactly as sent: they are RFC 3339 UTC instants and no timezone conversion is applied, unlike the form in plnnrly, which collects local wall-clock time. Omit end for an absence that is still running; it then reaches through now everywhere it is read, so close it when the employee returns. Naming a user_id or manager_id additionally requires read access to users (users::read) and a token covering that prefix, because the reference is checked against what the caller may see. Nothing prevents two overlapping absences for one employee.
Query parameters
Unknown parameters are refused with 400, naming the parameter.
Request headers
A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.
Request body
Unknown keys are refused with 422, naming the key.
The employee this absence is for. Writing it requires the absences::manage permission.
Manager who filed or approved the absence, or null when none was recorded. The foreign key nulls on delete, so removing the manager leaves the absence behind unattributed.
When the absence ends, or null while it is still running. An ongoing absence reaches through now everywhere it is read (planning capacity and reporting both count it), and that reach is uncapped, so an absence nobody closed keeps consuming capacity. RFC 3339 UTC.
Must be on or after start.
Response 201
Returns a Absence in the detail view.
Headers
ETag- A strong validator of exactly this representation.
Idempotency-Replayedtruewhen this response was replayed from a storedIdempotency-Keyrather than produced by a new write.Location- The absolute URL of the created or queued resource.
RateLimit- The IETF
httpapi-ratelimit-headersform of your remaining allowance on the tightest bucket this request touched. RateLimit-Policy- The ceiling and window of that bucket, as
<limit>;w=<seconds>. X-Request-Id- The server-generated ULID correlating this response with our logs.
Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning
The employee this absence is for. Writing it requires the absences::manage permission.
The employee the absence is for. Renders as an {"id": N} reference unless expanded, and stays a reference when the employee has since been deleted.
Manager who filed or approved the absence, or null when none was recorded. The foreign key nulls on delete, so removing the manager leaves the absence behind unattributed.
The manager who filed or approved the absence; absent when none was recorded.
When the absence ends, or null while it is still running. An ongoing absence reaches through now everywhere it is read (planning capacity and reporting both count it), and that reach is uncapped, so an absence nobody closed keeps consuming capacity. RFC 3339 UTC.
Errors
409 Conflict.
415 Unsupported media type.
422 Unprocessable content.
7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503
400 Bad request.
idempotency-key-requiredinvalid-cursorinvalid-query-parametermalformed-requestunsupported-parameter
401 Unauthenticated.
404 Not found.
406 Not acceptable.
429 Too many requests.
500 Server error.
503 Service unavailable.
This path allows GET, POST. Anything else answers 405.
Something wrong or missing on this page? Tell us