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.

Identifying absences with an external ID

Use externalId when you sync absences from another system, such as an Outlook calendar or an HR tool. You give the absence your own unique identifier when you create it. Later updates and deletions can then target that exact absence, without relying on the title, which does not have to be unique.

• externalId is optional. Absences created without it, including all absences created before this feature, keep working as before and can still be targeted by title or absence ID.

• It must be unique per user. Two different users can each have an absence with the same externalId, but one user cannot have two.

• It is a string of up to 255 characters. Surrounding spaces are removed. Matching is exact and case-sensitive.

• It is only available in the REST API. It is not shown in the app's UI and is not available in the automation actions.

• When you pass it as a query parameter (Edit and Delete), URL-encode the value. Characters such as /, + and =, which are common in calendar IDs, must be encoded.

• If a request contains externalId together with title, absenceId, date or from/to, the externalId decides which absence is affected.

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>",
      "externalId": "<your_unique_id>"
  }
  

  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.",
      "externalId": "outlook-040000008200E00074C5B7101A82E008"
  }
  

• 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: All responses are JSON objects with a message property. The response to a successful request does not contain the absence or its ID. To target the absence later, set an externalId.

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 whose absence you want to edit.

  • One of the following identifies the absence:

    • externalId: the external ID you set when the absence was created (recommended)

    • title: the title of the absence. If the user has several absences with this title, the first one is edited.

    • absenceId: the internal absence ID

• 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>,
      "externalId": "<new_unique_id>"
  }
  

  externalId in the body changes the absence's external ID. Send null or "" to remove it. Leave it out to keep the current one.

  Example: PUT <endpoint>?user=jane@example.com&externalId=outlook-040000008200E00074C5B7101A82E008

  JSON

  {
      "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: All responses are JSON objects with a message property.

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 whose absence you want to delete.

  • One of the following is required:

    • externalId: deletes the absence with this external ID (recommended)

    • title: deletes the first absence with this title

    • absenceId: deletes the absence with this internal ID

    • date: deletes all absences planned for this date

    • from and to: deletes all absences planned in this date range

  • If externalId is provided, only that absence is deleted, even if date or from/to are also sent.

• 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: All responses are JSON objects with a message property. The response to a successful request does not contain the absence ID.

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