Skip to main content
Skip table of contents

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.

image-20240724-071156.png

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.