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	`OK`	JSON array with absences
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use GET method." }`	Another method than GET has been used to call the endpoint.
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token." }`	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	`Not found`	JSON `{ error: true, message: "We couldn't find an user with the provided email address." }`	No user could be found with the provided email address.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to view this data." }`	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	`Created`	JSON object of new absence including new id. JSON `{ id: <new_absence_id>, title: <new_absence_title>, type: <new_absence_type>, start: <new_absence_start>, end: <new_absence_end>, message: <new_absence_message> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Saving new absence not possible at the moment. Please try again." }`	An error occurred when the new absence is saved.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use POST method." }`	Another method than POST has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "<Reason for error in request body>" }`	The error can be returned for multiple reasons: the format of the request body isn’t correct provided start date is later than end date of the absence required fields missing in request body the provided absence type is invalid the provided dates aren’t in format `YYYY-MM-DD`
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token." }`	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	`Not found`	JSON `{ error: true, message: "We couldn't find an user with the provided email address." }`	No user could be found with the provided email address.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to create an absence for this user." }`	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	`Created`	JSON object of edited absence. JSON `{ id: <new_absence_id>, title: <new_absence_title>, type: <new_absence_type>, start: <new_absence_start>, end: <new_absence_end>, message: <new_absence_message> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Saving absence not possible at the moment. Please try again." }`	An error occurred when the edited absence is saved.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use PUT method." }`	Another method than PUT has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "<Reason for error in request body>" }`	The error can be returned for multiple reasons: the format of the request body isn’t correct start date would be later than end date of the absence after editing id of absence to be edited is missing in the request body provided absence type is invalid provided dates aren’t in format `YYYY-MM-DD`
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token." }`	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	`Not found`	JSON `{ error: true, message: "We couldn't find an user with the provided email address." }`	No user could be found with the provided email address.
404	`Not found`	JSON `{ error: true, message: "Invalid absence ID. The absence with the provided ID doesn't exist." }`	No absence to edit could be found for the provided id.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to create an absence for this user." }`	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	`OK`	Id of the absence that has been deleted JSON `{ id: <absence_id> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Deleting absence not possible at the moment. Please try again." }`	An error occurred when deleting the absence.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use DELETE method." }`	Another method than DELETE has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "Missing required parameters. Absence ID is missing." }`	No id for an absence to be deleted has been provided as parameter.
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token." }`	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	`Not found`	JSON `{ error: true, message: "We couldn't find an user with the provided email address." }`	No user could be found with the provided email address.
404	`Not found`	JSON `{ error: true, message: "Invalid absence ID. The absence with the provided ID doesn't exist." }`	No absence to delete could be found for the provided id.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to delete absences of this user." }`	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.