REST API Endpoints Documentation

Use the REST API to manage out of office rules programmatically. Create, update, and delete rules through custom integrations, Jira Automations, or third-party tools.

What you can do

The REST API lets you manage out of office rules outside the app interface. You can create rules for users or yourself, update existing rules (dates, coverers, messages), retrieve active rules, and delete rules when no longer needed.

Use cases include bulk rule creation, integration with HR systems, or automated rule management through Jira Automations.

Base URL

All API requests use this base URL:

Authentication

Every request needs a token in the Authorization header.

There are 2 token scopes available.

• Admin Scope: Manage rules for all users in your Jira instance. Only available to Jira admins.

• Read/Write/Delete Scope: Manage only your own rules. Available to all users when enabled in General Settings.

Create a token (Jira Admin)

Jira admins can create tokens with either scope depending on their needs.

Navigate to Out of Office Assistant in Jira. Click User Administration and go to the REST API Permissions tab. Click Create Token and select yourself as the user.

Choose your scope:

• Admin: Manage rules for all users (for automations, bulk operations, or integrations)

• Read/Write/Delete: Manage only your own rules

Copy the token (shown only once) and click OK.

Create a token (Regular User)

Regular users can create tokens to manage their own rules via API. This must be enabled by an admin in the Global Settings under "Allow users to create their own REST API tokens".

Navigate to Out of Office Assistant and click the Integrations tab. Click Connect, copy the displayed token (shown only once), and click Close.

This token uses the Read/Write/Delete scope and only works for your own rules.

Available endpoints

The API provides two sets of endpoints based on your token scope.

Admin endpoints

Use these with an admin token to manage rules for any user.

• GET /outofoffice/rules retrieves all rules for one or multiple users.

• POST /outofoffice/rules creates rules for any user.

• PUT /outofoffice/rules updates existing rules.

• DELETE /outofoffice/rules deletes rules.

User endpoints

Use these with a Read/Write/Delete scope token to manage your own rules.

• GET /outofoffice/myrules retrieves your rules.

• POST /outofoffice/myrules creates a new rule for yourself.

• PUT /outofoffice/myrules updates your rules.

• DELETE /outofoffice/myrules deletes your rules.

Request structure

GET - Retrieve rules (Admin)

Retrieve rules for one or multiple users.

Endpoint: GET /outofoffice/rules

Required query parameters:

• accountIds: Comma-separated list of user account IDs

Request example (single user):

Request example (multiple users):

Response example:

The response returns an array of user objects. Each user object contains their account details and an array of active rules. If a user has no rules, the rules array is empty.

POST - Create rules (Admin)

Create one or multiple rules for users.

Endpoint: POST /outofoffice/rules

Required fields:

• accountId: The user's Atlassian account ID

• startDate: Start date in YYYY-MM-DD format

• project.id: Jira project ID (numeric ID, not project key)

Optional fields (must be included but can be empty):

• endDate: End date in YYYY-MM-DD format

• jqlFilterName: JQL filter to restrict affected issues

• coverers: Array of coverer account IDs

• approverCoverers: Array with one approver coverer account ID

• approverField: Custom field configuration for approvers

• message: Out of office message posted as comment

• doNotShareWithCustomer: Hide status from portal users (default: false)

• paused: Create rule in paused state (default: false)

• oooMentions: Mention tag configuration

To find the project ID, use the Jira API endpoint: <baseURL>/rest/api/3/project/<projectKey>

Request example:

Response example:

PUT - Update rules (Admin)

Update existing rules. Include the rule ID and only the fields you want to change.

Endpoint: PUT /outofoffice/rules

Required fields:

• accountId: The user's Atlassian account ID

• id: The rule ID (obtained from GET request)

Optional fields:
You only need to include the fields you want to update. All other fields from the original rule remain unchanged.

Request example:

In this example, we update the start date and switch from a project filter to a JQL filter. Setting project to null removes the project restriction.

Response example:

DELETE - Delete rules (Admin)

Delete one or multiple rules by their IDs.

Endpoint: DELETE /outofoffice/rules

Required query parameters:

• accountId: The user's Atlassian account ID

• ruleIds: Comma-separated list of rule IDs to delete

Request example (single rule):

Request example (multiple rules):

Response example:

Error responses

400 Bad Request
Invalid parameters or malformed request body

401 Unauthorized
Missing or invalid token

403 Forbidden
Token has no permission for this operation

Testing with Swagger Hub

The API is documented on Swagger Hub. You can view request structures and response examples.

[Screenshot: Swagger Hub - Endpoints Übersicht mit admins und users Bereichen]

Visit the documentation: https://app.swaggerhub.com/apis/resolution-cloud/jira-outofoffice/1.0.2

The Swagger interface shows all endpoints, required fields, and example payloads. Use it as a reference when building your integration.

Need help?

If you encounter issues or have questions about the API, check the Swagger Hub documentation for request examples. Verify your token has the correct scope and ensure account IDs are valid and active in your Jira instance.

Contact support if you need assistance.