API Documentation
Please note: Each instance has unique endpoints, which can be retrieved on the user absence planner settings page in the Jira administration by system administrators. The email address of the user you want to manage absences for is always required as parameter.
Authentication
When accessing any of the REST API endpoints mentioned below, users must authenticate themselves using the email associated with their Atlassian account and an app API token obtainable from the app's administration.
To generate your token, navigate to Apps → Manage your Apps → User Absence Planner Settings (left sidebar) → API token tab.

You have access to a comprehensive list of all your generated tokens, along with details on their creation and last usage. To generate a new API token, simply click on the designated button located at the top of the page.
Please remember that your generated token is only visible during the creation process in the modal dialog. It is crucial to copy it to your clipboard and securely store it. Once generated, the token cannot be displayed again. In case you misplace your token and fail to save it, you will need to delete the current token and generate a new one.
REST API Endpoints
1. Get Absences
Retrieve all absences for a specific user.
Method: GET
Parameters:
user: The email address of the user you want to get absences for.
Body: None
Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → User Absence Planner Settings → REST API Endpoints tab
Responses:
Status code | Status text | Body | Reason |
---|---|---|---|
200 |
| JSON array with absences | |
405 |
|
JSON
| Another method than GET has been used to call the endpoint. |
401 |
|
JSON
| Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials. |
404 |
|
JSON
| No user could be found with the provided email address. |
403 |
|
JSON
| Absences for another user than the one calling the api were requested, but the user calling the api doesn’t have the permission to view absences of other users. |
2. Create Absence
Create a new absence entry for a specific user.
Method: POST
Parameters:
user: The email address of the user you want to create an absence for.
Body:
JSON{ "title": "<title>", "type": "<type>", "start": "<date_format_YYYY-MM-DD>", "end": "<date_format_YYYY-MM-DD>", "message": "<message>" }
Example:
JSON{ "title": "Summer holidays", "type": "Holiday", "start": "2024-08-03", "end": "2024-08-14", "message": "I am currently out of office with no access to my Jira tasks." }
All values required except message.
Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → User Absence Planner Settings → REST API Endpoints tab
Responses:
Status code | Status text | Body | Reason |
---|---|---|---|
201 |
| JSON object of new absence including new id.
JSON
| |
500 |
|
JSON
| An error occurred when the new absence is saved. |
405 |
|
JSON
| Another method than POST has been used to call the endpoint. |
400 |
|
JSON
| The error can be returned for multiple reasons:
|
401 |
|
JSON
| Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials. |
404 |
|
JSON
| No user could be found with the provided email address. |
403 |
|
JSON
| An absence for another user than the one calling the api should be created, but the user calling the api doesn’t have the permission to create absences for other users. |
3. Edit Absence
Edit an existing absence entry for a specific user.
Method: PUT
Parameters:
user: The email address of the user you want to edit an absence for.
Body:
JSON{ "id": "<abesence_id>", "title": "<title>", "type": "<type>", "start": "<date_format_YYYY-MM-DD>", "end": "<date_format_YYYY-MM-DD>", "message": "<message>" }
Example:
JSON{ "id": "_.gee4i65", "end": "2024-08-21", "message": "My holidays have been extended until August 21." }
Only absence id is required. The absence attributes included in the body will be updated.
Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → User Absence Planner Settings → REST API Endpoints tab
Responses:
Status code | Status text | Body | Reason |
---|---|---|---|
201 |
| JSON object of edited absence.
JSON
| |
500 |
|
JSON
| An error occurred when the edited absence is saved. |
405 |
|
JSON
| Another method than PUT has been used to call the endpoint. |
400 |
|
JSON
| The error can be returned for multiple reasons:
|
401 |
|
JSON
| Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials. |
404 |
|
JSON
| No user could be found with the provided email address. |
404 |
|
JSON
| No absence to edit could be found for the provided id. |
403 |
|
JSON
| An absence for another user than the one calling the api should be edited, but the user calling the api doesn’t have the permission to edit absences for other users. |
4. Delete Absence
Delete an existing absence entry for a specific user.
Method: DELETE
Parameters:
user: The email address of the user you want to edit an absence for.
id: id of the absence to be deleted
Body: None
Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → User Absence Planner Settings → REST API Endpoints tab
Responses:
Status code | Status text | Body | Reason |
---|---|---|---|
200 |
| Id of the absence that has been deleted
JSON
| |
500 |
|
JSON
| An error occurred when deleting the absence. |
405 |
|
JSON
| Another method than DELETE has been used to call the endpoint. |
400 |
|
JSON
| No id for an absence to be deleted has been provided as parameter. |
401 |
|
JSON
| Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials. |
404 |
|
JSON
| No user could be found with the provided email address. |
404 |
|
JSON
| No absence to delete could be found for the provided id. |
403 |
|
JSON
| Absence for another user than the one calling the api should be deleted, but the user calling the api doesn’t have the permission to delete absences for other users. |