action confluence_find_users_by_query {
  label: "Find users by query"
  description: "Finds users with a structured query and returns a [paginated](#pagination) list of user details.\n\nThis operation takes the users in the range defined by `startAt` and `maxResults`, up to the thousandth user, and then returns only the users from that range that match the structured query. This means the operation usually returns fewer users than specified in `maxResults`. To get all the users who match the structured query, use [Get all users](#api-rest-api-3-users-search-get) and filter the records in your code.\n\n**[Permissions](#permissions) required:** *Browse users and groups* [global permission](https://confluence.atlassian.com/x/x4dKLg).\n\nThe query statements are:\n\n *  `is assignee of PROJ` Returns the users that are assignees of at least one issue in project *PROJ*.\n *  `is assignee of (PROJ-1, PROJ-2)` Returns users that are assignees on the issues *PROJ-1* or *PROJ-2*.\n *  `is reporter of (PROJ-1, PROJ-2)` Returns users that are reporters on the issues *PROJ-1* or *PROJ-2*.\n *  `is watcher of (PROJ-1, PROJ-2)` Returns users that are watchers on the issues *PROJ-1* or *PROJ-2*.\n *  `is voter of (PROJ-1, PROJ-2)` Returns users that are voters on the issues *PROJ-1* or *PROJ-2*.\n *  `is commenter of (PROJ-1, PROJ-2)` Returns users that have posted a comment on the issues *PROJ-1* or *PROJ-2*.\n *  `is transitioner of (PROJ-1, PROJ-2)` Returns users that have performed a transition on issues *PROJ-1* or *PROJ-2*.\n *  `[propertyKey].entity.property.path is \"property value\"` Returns users with the entity property value.\n\nThe list of issues can be extended as needed, as in *(PROJ-1, PROJ-2, ... PROJ-n)*. Statements can be combined using the `AND` and `OR` operators to form more complex queries. For example:\n\n`is assignee of PROJ AND [propertyKey].entity.property.path is \"property value\"`"
  provider: confluence
  method: GET
  path: "/rest/api/3/user/search/query"
  encoding: json
  input: {
    type: "object"
    properties: {
      maxResults: {
        type: "integer"
        format: "int32"
      }
      query: {
        type: "string"
      }
      startAt: {
        type: "integer"
        format: "int64"
      }
    }
    required: ["query"]
    additionalProperties: false
  }
  output: {
    type: "object"
    description: "A page of items."
    properties: {
      isLast: {
        type: "boolean"
        description: "Whether this is the last page."
      }
      maxResults: {
        type: "integer"
        format: "int32"
        description: "The maximum number of items that could be returned."
      }
      nextPage: {
        type: "string"
        format: "uri"
        description: "If there is another page of results, the URL of the next page."
      }
      self: {
        type: "string"
        format: "uri"
        description: "The URL of the page."
      }
      startAt: {
        type: "integer"
        format: "int64"
        description: "The index of the first item returned."
      }
      total: {
        type: "integer"
        format: "int64"
        description: "The number of items returned."
      }
      values: {
        type: "array"
        description: "The list of items."
        items: {
          type: "object"
          description: "A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:\n\n *  User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, `displayName` provides an indication and other parameters have default values or are blank (for example, email is blank).\n *  User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, `accountId` returns *unknown* and all other parameters have fallback values.\n *  User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values."
          properties: {
            accountId: {
              type: "string"
              description: "The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Required in requests."
            }
            accountType: {
              type: "string"
              description: "The user account type. Can take the following values:\n\n *  `atlassian` regular Atlassian user account\n *  `app` system account used for Connect applications and OAuth to represent external systems\n *  `customer` Jira Service Desk account representing an external service desk"
              enum: ["atlassian", "app", "customer", "unknown"]
            }
            active: {
              type: "boolean"
              description: "Whether the user is active."
            }
            applicationRoles: {
              description: "The application roles the user is assigned to."
              type: "object"
            }
            avatarUrls: {
              description: "The avatars of the user."
              type: "object"
            }
            displayName: {
              type: "string"
              description: "The display name of the user. Depending on the user’s privacy setting, this may return an alternative value."
            }
            emailAddress: {
              type: "string"
              description: "The email address of the user. Depending on the user’s privacy setting, this may be returned as null."
            }
            expand: {
              type: "string"
              description: "Expand options that include additional user details in the response."
            }
            groups: {
              description: "The groups that the user belongs to."
              type: "object"
            }
            key: {
              type: "string"
              description: "This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details."
            }
            locale: {
              type: "string"
              description: "The locale of the user. Depending on the user’s privacy setting, this may be returned as null."
            }
            name: {
              type: "string"
              description: "This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details."
            }
            self: {
              type: "string"
              format: "uri"
              description: "The URL of the user."
            }
            timeZone: {
              type: "string"
              description: "The time zone specified in the user's profile. Depending on the user’s privacy setting, this may be returned as null."
            }
          }
          additionalProperties: false
        }
      }
    }
    additionalProperties: false
  }
}