API Documentation

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 either from the app's administration, or from the api token tab on the User Absence Planner global page.

To generate your token as Jira administrator, navigate to Marketplace Apps → User Absence Planner Settings (left sidebar) → API token tab.

Personal API token

Click Create new API token to generate a token for your admin Jira account. In the dialog, enter a name and choose an expiration: 30, 90, 180, 365 days, or never.

API token for Service Accounts

For Atlassian service accounts, create API tokens from the API token tab using its button. This is useful when you use service accounts for external integrations and interfaces.

If non-admin users receive permission to use the API, they will also see an API token tab on the global User Absence Planner page.

You can get the REST API endpoints from the corresponding button.

REST API Endpoints

1. Create Absence

Create a new absence entry for a specific user.

• Method: POST

• Parameters:

  • user: The email address or account id 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>",
      "startTime": "<time_HH:mm_or_h:mm_AM/PM>",
      "endTime": "<time_HH:mm_or_h:mm_AM/PM>"
  }
  

  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."
  }
  

• Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Marketplace Apps → User Absence Planner Settings → REST API Endpoints tab

Responses:

{
  id: <new_absence_id>,
  title: <new_absence_title>,
  type: <new_absence_type>,
  start: <new_absence_start>,
  end: <new_absence_end>,
  message: <new_absence_message>
}

{
  error: true,
  message: "Saving new absence not possible at the moment. Please try again."
}

{
  error: true,
  message: "Method not allowed. Please use POST method."
}

{
  error: true,
  message: "<Reason for error in request body>"
}

{
  error: true,
  message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token."
}

{
  error: true,
  message: "We couldn't find an user with the provided email address."
}

{
  error: true,
  message: "Access denied - you do not have permission to create an absence for this user."
}

2. Edit Absence

Edit an existing absence entry for a specific user.

• Method: PUT

• Parameters:

  • user: The email address or account id of the user you want to edit an absence for.

  • title or absenceId: Title or absence id of the absence you want to edit

• Body:

  JSON

  {
      "title": "<title>",
      "type": "<type>",
      "start": "<date_format_YYYY-MM-DD>",
      "end": "<date_format_YYYY-MM-DD>",
      "message": "<message>",
      "startTime": "<time_HH:mm_or_h:mm_AM/PM>",
      "endTime": "<time_HH:mm_or_h:mm_AM/PM>",
      "allDay": <true_or_false>
  }
  

  Example:

  JSON

  {
      "id": "_.gee4i65",
      "end": "2024-08-21",
      "message": "My holidays have been extended until August 21."
  }
  

• Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Marketplace Apps → User Absence Planner Settings → REST API Endpoints tab

Responses:

{
  id: <new_absence_id>,
  title: <new_absence_title>,
  type: <new_absence_type>,
  start: <new_absence_start>,
  end: <new_absence_end>,
  message: <new_absence_message>
}

{
  error: true,
  message: "Saving absence not possible at the moment. Please try again."
}

{
  error: true,
  message: "Method not allowed. Please use PUT method."
}

{
  error: true,
  message: "<Reason for error in request body>"
}

{
  error: true,
  message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token."
}

{
  error: true,
  message: "We couldn't find an user with the provided email address."
}

{
  error: true,
  message: "Invalid absence ID. The absence with the provided ID doesn't exist."
}

{
  error: true,
  message: "Access denied - you do not have permission to create an absence for this user."
}

3. Delete Absence

Delete an existing absence entry for a specific user.

• Method: DELETE

• Parameters:

  • user: The email address or account id of the user you want to edit an absence for.

  • One of the following is required:

    • title: Title of the absence you want to delete

    • absenceId: Absence id of the absence you want to delete

    • date: Delete all absences that are planned for this date

    • Date range - from and to: Delete all absences that are planned in this date range

• Body: None

• Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Marketplace Apps → User Absence Planner Settings → REST API Endpoints tab

Responses:

{
  id: <absence_id>
}

{
  error: true,
  message: "Deleting absence not possible at the moment. Please try again."
}

{
  error: true,
  message: "Method not allowed. Please use DELETE method."
}

{
  error: true,
  message: "Missing required parameters. Absence ID is missing."
}

{
  error: true,
  message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token."
}

{
  error: true,
  message: "We couldn't find an user with the provided email address."
}

{
  error: true,
  message: "Invalid absence ID. The absence with the provided ID doesn't exist."
}

{
  error: true,
  message: "Access denied - you do not have permission to delete absences of this user."
}

4. Check Availability

Check availability for a specific user on the current day.

• Method: GET

• Parameters:

  • user: The email address or account id of the user you want to edit an absence for.

• Body: None

• Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Marketplace Apps → User Absence Planner Settings → REST API Endpoints tab