Slack Users API

openapi: 3.2.0
info:
  title: Slack Web Users API
  description: The Slack Web API is an HTTP-based interface that provides access to all of Slack's platform features. It consists of over 200 methods organized by functional area (chat, conversations, users, files, admin, and more) that apps call over HTTPS with JSON payloads and receive JSON responses. All methods require authentication via OAuth tokens (bot or user) with granular permission scopes, and are subject to tiered rate limits. The Web API supports cursor-based pagination for large result sets and provides consistent error handling across all endpoints.
  version: 1.0.0
  termsOfService: https://slack.com/terms-of-service/api
  contact:
    name: Slack Developer Support
    url: https://docs.slack.dev
  license:
    name: Slack API Terms of Service
    url: https://slack.com/terms-of-service/api
servers:
- url: https://slack.com/api
  description: Slack Web API production server
security:
- bearerAuth: []
tags:
- name: Users
  description: Find and manage user information
paths:
  /users.list:
    get:
      tags:
      - Users
      summary: Slack List All Users
      description: Lists all users in a Slack team. Results are paginated with cursor-based pagination.
      operationId: usersList
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/users.list
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
      - name: include_locale
        in: query
        description: Set to true to receive the locale for users.
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          maximum: 1000
      - name: team_id
        in: query
        description: Required for org-wide app tokens.
        schema:
          type: string
      responses:
        '200':
          description: User list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  cache_ts:
                    type: integer
                  response_metadata:
                    $ref: '#/components/schemas/ResponseMetadata'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users.info:
    get:
      tags:
      - Users
      summary: Slack Get Information About a User
      description: Gets information about a user. Returns a user object with profile information, timezone, admin status, and more.
      operationId: usersInfo
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/users.info
      parameters:
      - name: user
        in: query
        required: true
        description: User to get info on.
        schema:
          type: string
      - name: include_locale
        in: query
        description: Set to true to receive the locale for this user.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: User information retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  user:
                    $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users.lookupByEmail:
    get:
      tags:
      - Users
      summary: Slack Find a User by Email Address
      description: Find a user with an email address. Requires users:read.email scope.
      operationId: usersLookupByEmail
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/users.lookupByEmail
      parameters:
      - name: email
        in: query
        required: true
        description: An email address belonging to a user in the workspace.
        schema:
          type: string
          format: email
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  user:
                    $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users.getPresence:
    get:
      tags:
      - Users
      summary: Slack Get User Presence Information
      description: Gets user presence information.
      operationId: usersGetPresence
      externalDocs:
        description: API method documentation
        url: https://docs.slack.dev/reference/methods/users.getPresence
      parameters:
      - name: user
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Presence retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  presence:
                    type: string
                    enum:
                    - active
                    - away
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    User:
      type: object
      description: A Slack user object representing a workspace member with their profile, roles, and settings.
      properties:
        id:
          type: string
          description: The unique identifier for this user.
          example: abc123
        team_id:
          type: string
          description: The workspace team ID this user belongs to.
          example: '500123'
        name:
          type: string
          description: The user's username.
          example: Example Title
        deleted:
          type: boolean
          description: Whether the user has been deactivated.
          example: true
        color:
          type: string
          description: A hex color code used in certain client displays for this user.
          example: example_value
        real_name:
          type: string
          description: The user's real name.
          example: example_value
        tz:
          type: string
          description: The user's timezone identifier (e.g., "America/Los_Angeles").
          example: example_value
        tz_label:
          type: string
          description: Descriptive label for the user's timezone.
          example: example_value
        tz_offset:
          type: integer
          description: The user's timezone offset from UTC in seconds.
          example: 10
        profile:
          type: object
          description: The user's profile information.
          properties:
            avatar_hash:
              type: string
            status_text:
              type: string
              description: The user's current status text.
            status_emoji:
              type: string
              description: The user's current status emoji.
            status_expiration:
              type: integer
              description: Unix timestamp when the status expires.
            real_name:
              type: string
            display_name:
              type: string
              description: The display name the user has chosen.
            real_name_normalized:
              type: string
            display_name_normalized:
              type: string
            email:
              type: string
              format: email
              description: The user's email address. Requires users:read.email scope.
            first_name:
              type: string
            last_name:
              type: string
            title:
              type: string
              description: The user's job title.
            phone:
              type: string
            skype:
              type: string
            image_24:
              type: string
              format: uri
            image_32:
              type: string
              format: uri
            image_48:
              type: string
              format: uri
            image_72:
              type: string
              format: uri
            image_192:
              type: string
              format: uri
            image_512:
              type: string
              format: uri
            image_original:
              type: string
              format: uri
            team:
              type: string
          example: example_value
        is_admin:
          type: boolean
          description: Whether the user is a workspace admin.
          example: true
        is_owner:
          type: boolean
          description: Whether the user is a workspace owner.
          example: true
        is_primary_owner:
          type: boolean
          description: Whether the user is the primary workspace owner.
          example: true
        is_restricted:
          type: boolean
          description: Whether the user is a guest with single-channel access.
          example: true
        is_ultra_restricted:
          type: boolean
          description: Whether the user is a single-channel guest.
          example: true
        is_bot:
          type: boolean
          description: Whether the user is a bot.
          example: true
        is_app_user:
          type: boolean
          description: Whether the user is an app user.
          example: true
        updated:
          type: integer
          description: Unix timestamp of when the user was last updated.
          example: 10
        has_2fa:
          type: boolean
          description: Whether the user has two-factor authentication enabled.
          example: true
        locale:
          type: string
          description: IETF language code for the user. Only included when specifically requested.
          example: example_value
    ResponseMetadata:
      type: object
      description: Metadata for paginated responses containing cursor information.
      properties:
        next_cursor:
          type: string
          description: An opaque cursor to use in the next request to get the next page of results. Empty string indicates no more results.
          example: example_value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Slack API uses Bearer token authentication. Pass a bot token or user token in the Authorization header.