Slack's Users API is a set of Web API methods that let your app discover and work with people in a Slack workspace. It can list members, fetch details for a specific user, look up users by email, and retrieve profile data such as names, photos, status, time zones, and custom fields. Where permitted, it can also read presence and update a user's profile or photo with the proper user-level authorization.
openapi: 3.1.0
info:
version: "1.0"
title: Slack Users API
description: "Slack\x19s Users API is a set of Web API methods that let your app discover and work with people in a Slack workspace. It can list members, fetch details for a specific user, look up users
by email, and retrieve profile data such as names, photos, status, time zones, and custom fields. Where permitted, it can also read presence and update a user\x19s profile or photo with the proper user-level
authorization. Developers use it to map real identities to Slack user IDs, personalize experiences, resolve mentions and DMs, and distinguish between human, bot, and app users. Access to specific data
and actions depends on scopes (for example, users:read, users:read.email, users.profile:read/write), and certain capabilities like presence have additional restrictions. For provisioning and enterprise
directory management, Slack\x19s SCIM API is used instead."
paths:
/users.conversations:
get:
tags:
- Conversations
- Get
- Users
description: List conversations the calling user may access.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.conversations
operationId: getUsersConversations
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `conversations:read`'
schema:
type: string
- name: user
in: query
description: >-
Browse conversations by a specific user ID's membership. Non-public
channels are restricted to those where the calling user shares
membership.
schema:
type: string
- name: types
in: query
description: >-
Mix and match channel types by providing a comma-separated list of
any combination of `public_channel`, `private_channel`, `mpim`, `im`
schema:
type: string
- name: exclude_archived
in: query
description: Set to `true` to exclude archived channels from the list
schema:
type: boolean
- name: limit
in: query
description: >-
The maximum number of items to return. Fewer than the requested
number of items may be returned, even if the end of the list hasn't
been reached. Must be an integer no larger than 1000.
schema:
type: integer
- name: cursor
in: query
description: >-
Paginate through collections of data by setting the `cursor`
parameter to a `next_cursor` attribute returned by a previous
request's `response_metadata`. Default value fetches the first
"page" of the collection. See [pagination](/docs/pagination) for
more detail.
schema:
type: string
responses:
'200':
description: >-
Typical success response with only public channels. Note how
`num_members` and `is_member` are not returned like typical
`conversations` objects.
content:
application/json:
schema:
title: users.conversations success schema
required:
- channels
- ok
type: object
properties:
channels:
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/objs_conversation'
ok:
$ref: '#/components/schemas/defs_ok_true'
response_metadata:
type: object
additionalProperties: false
additionalProperties: true
description: >-
Schema for successful response from users.conversations
method. Returned conversation objects do not include
`num_members` or `is_member`
example:
channels:
- created: 1449252889
creator: U012A3CDE
id: C012AB3CD
is_archived: false
is_channel: true
is_ext_shared: false
is_general: true
is_group: false
is_im: false
is_mpim: false
is_org_shared: false
is_pending_ext_shared: false
is_private: false
is_shared: false
name: general
name_normalized: general
pending_shared: []
previous_names: []
purpose:
creator: ''
last_set: 0
value: >-
This channel is for team-wide communication and
announcements. All team members are in this channel.
topic:
creator: ''
last_set: 0
value: Company-wide announcements and work-based matters
unlinked: 0
- created: 1449252889
creator: U061F7AUR
id: C061EG9T2
is_archived: false
is_channel: true
is_ext_shared: false
is_general: false
is_group: false
is_im: false
is_mpim: false
is_org_shared: false
is_pending_ext_shared: false
is_private: false
is_shared: false
name: random
name_normalized: random
pending_shared: []
previous_names: []
purpose:
creator: ''
last_set: 0
value: >-
A place for non-work-related flimflam, faffing,
hodge-podge or jibber-jabber you'd prefer to keep out of
more focused work-related channels.
topic:
creator: ''
last_set: 0
value: Non-work banter and water cooler conversation
unlinked: 0
ok: true
response_metadata:
next_cursor: dGVhbTpDMDYxRkE1UEI=
default:
description: Typical error response
content:
application/json:
schema:
title: users.conversations error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- method_not_supported_for_channel_type
- missing_scope
- invalid_types
- invalid_cursor
- invalid_limit
- not_authed
- invalid_auth
- account_inactive
- token_revoked
- no_permission
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- fatal_error
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties: false
description: Schema for error response from users.conversations method
example:
error: invalid_auth
ok: false
security:
- slackAuth:
- channels:read
- groups:read
- im:read
- mpim:read
summary: Slack Get Users Conversations
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.deletePhoto:
post:
tags:
- Post
- Users
description: Delete the user profile photo
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.deletePhoto
operationId: postUsersDeletephoto
requestBody:
content:
application/x-www-form-urlencoded:
schema:
required:
- token
type: object
properties:
token:
type: string
description: 'Authentication token. Requires scope: `users.profile:write`'
required: true
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: users.deletePhoto schema
required:
- ok
type: object
properties:
ok:
$ref: '#/components/schemas/defs_ok_true'
additionalProperties: false
description: Schema for successful response from users.deletePhoto method
example:
ok: true
default:
description: Typical error response
content:
application/json:
schema:
title: users.deletePhoto error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- not_authed
- invalid_auth
- account_inactive
- token_revoked
- no_permission
- org_login_required
- user_is_bot
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- fatal_error
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties: false
description: Schema for error response from users.deletePhoto method
example:
error: invalid_auth
ok: false
security:
- slackAuth:
- users.profile:write
summary: Slack Post Users Deletephoto
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.getPresence:
get:
tags:
- Get
- Users
description: Gets user presence information.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.getPresence
operationId: getUsersGetpresence
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `users:read`'
required: true
schema:
type: string
- name: user
in: query
description: User to get presence info on. Defaults to the authed user.
schema:
type: string
responses:
'200':
description: >-
When requesting information for a different user, this method just
returns the current presence (either `active` or `away`).
content:
application/json:
schema:
title: 'API method: users.getPresence'
required:
- ok
- presence
type: object
properties:
auto_away:
type: boolean
connection_count:
type: integer
last_activity:
type: integer
manual_away:
type: boolean
ok:
$ref: '#/components/schemas/defs_ok_true'
online:
type: boolean
presence:
type: string
additionalProperties: true
description: >-
Generated from users.getPresence with shasum
e7251aec575d8863f9e0eb38663ae9dc26655f65
example:
ok: true
presence: active
default:
description: Typical error response
content:
application/json:
schema:
title: users.counts error schema
required:
- error
- ok
type: object
properties:
error:
type: string
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties:
type: object
properties: {}
description: Schema for error response users.getPresence method
example:
error: invalid_auth
ok: false
security:
- slackAuth:
- users:read
summary: Slack Get Users Getpresence
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.identity:
get:
tags:
- Get
- Identity
- Users
description: Get a user's identity.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.identity
operationId: getUsersIdentity
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `identity.basic`'
schema:
type: string
responses:
'200':
description: 'You will receive at a minimum the following information:'
content:
application/json:
schema:
title: users.identity schema
type: array
description: Schema for successful response from users.identity method
example:
ok: true
team:
id: T0G9PQBBK
user:
id: U0G9QF9C6
name: Sonny Whether
default:
description: Typical error response
content:
application/json:
schema:
title: users.identity error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- not_authed
- invalid_auth
- account_inactive
- token_revoked
- no_permission
- org_login_required
- user_is_bot
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- fatal_error
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties: false
description: Schema for error response from users.identity method
example:
error: account_inactive
ok: false
security:
- slackAuth:
- identity.basic
summary: Slack Get Users Identity
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.info:
get:
tags:
- Get
- Info
- Users
description: Gets information about a user.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.info
operationId: getUsersInfo
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `users:read`'
required: true
schema:
type: string
- name: include_locale
in: query
description: >-
Set this to `true` to receive the locale for this user. Defaults to
`false`
schema:
type: boolean
- name: user
in: query
description: User to get info on
schema:
type: string
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: users.info success schema
required:
- ok
- user
type: object
properties:
ok:
$ref: '#/components/schemas/defs_ok_true'
user:
$ref: '#/components/schemas/objs_user'
additionalProperties: true
description: Schema for successful response from users.info method
example:
ok: true
user:
color: 9f69e7
deleted: false
has_2fa: false
id: W012A3CDE
is_admin: true
is_app_user: false
is_bot: false
is_owner: false
is_primary_owner: false
is_restricted: false
is_ultra_restricted: false
name: spengler
profile:
avatar_hash: ge3b51ca72de
display_name: spengler
display_name_normalized: spengler
email: [email protected]
image_192: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_24: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_32: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_48: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_512: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_72: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_original: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
real_name: Egon Spengler
real_name_normalized: Egon Spengler
status_emoji: ':books:'
status_text: Print is dead
team: T012AB3C4
real_name: Egon Spengler
team_id: T012AB3C4
tz: America/Los_Angeles
tz_label: Pacific Daylight Time
tz_offset: -25200
updated: 1502138686
default:
description: Typical error response
content:
application/json:
schema:
title: users.info error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
error:
type: string
enum:
- user_not_found
- user_not_visible
- not_authed
- invalid_auth
- account_inactive
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties: false
description: Schema for error response from users.info method
example:
error: user_not_found
ok: false
security:
- slackAuth:
- users:read
summary: Slack Get Users Info
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.list:
get:
tags:
- Get
- Lists
- Users
description: Lists all users in a Slack team.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.list
operationId: getUsersList
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `users:read`'
schema:
type: string
- name: limit
in: query
description: >-
The maximum number of items to return. Fewer than the requested
number of items may be returned, even if the end of the users list
hasn't been reached. Providing no `limit` value will result in Slack
attempting to deliver you the entire result set. If the collection
is too large you may experience `limit_required` or HTTP 500 errors.
schema:
type: integer
- name: cursor
in: query
description: >-
Paginate through collections of data by setting the `cursor`
parameter to a `next_cursor` attribute returned by a previous
request's `response_metadata`. Default value fetches the first
"page" of the collection. See [pagination](/docs/pagination) for
more detail.
schema:
type: string
- name: include_locale
in: query
description: >-
Set this to `true` to receive the locale for users. Defaults to
`false`
schema:
type: boolean
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: users.list schema
required:
- cache_ts
- members
- ok
type: object
properties:
cache_ts:
type: integer
members:
minItems: 1
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/objs_user'
ok:
$ref: '#/components/schemas/defs_ok_true'
response_metadata:
$ref: '#/components/schemas/objs_response_metadata'
additionalProperties: false
description: Schema for successful response from users.list method
example:
cache_ts: 1498777272
members:
- color: 9f69e7
deleted: false
has_2fa: false
id: W012A3CDE
is_admin: true
is_app_user: false
is_bot: false
is_owner: false
is_primary_owner: false
is_restricted: false
is_ultra_restricted: false
name: spengler
profile:
avatar_hash: ge3b51ca72de
display_name: spengler
display_name_normalized: spengler
email: [email protected]
image_192: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_24: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_32: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_48: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_512: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_72: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
real_name: Egon Spengler
real_name_normalized: Egon Spengler
status_emoji: ':books:'
status_text: Print is dead
team: T012AB3C4
real_name: spengler
team_id: T012AB3C4
tz: America/Los_Angeles
tz_label: Pacific Daylight Time
tz_offset: -25200
updated: 1502138686
- color: 9f69e7
deleted: false
has_2fa: false
id: W07QCRPA4
is_admin: true
is_bot: false
is_owner: false
is_primary_owner: false
is_restricted: false
is_ultra_restricted: false
name: glinda
profile:
avatar_hash: 8fbdd10b41c6
display_name: Glinda the Fairly Good
display_name_normalized: Glinda the Fairly Good
email: [email protected]
first_name: Glinda
image_1024: https://a.slack-edge.com...png
image_192: https://a.slack-edge.com...png
image_24: https://a.slack-edge.com...png
image_32: https://a.slack-edge.com...png
image_48: https://a.slack-edge.com...png
image_512: https://a.slack-edge.com...png
image_72: https://a.slack-edge.com...png
image_original: https://a.slack-edge.com...png
last_name: Southgood
phone: ''
real_name: Glinda Southgood
real_name_normalized: Glinda Southgood
skype: ''
title: Glinda the Good
real_name: Glinda Southgood
team_id: T0G9PQBBK
tz: America/Los_Angeles
tz_label: Pacific Daylight Time
tz_offset: -25200
updated: 1480527098
ok: true
response_metadata:
next_cursor: dXNlcjpVMEc5V0ZYTlo=
default:
description: Typical error response
content:
application/json:
schema:
title: users.list error schema
required:
- error
- ok
type: object
properties:
callstack:
type: string
description: 'Note: PHP callstack is only visible in dev/qa'
error:
type: string
enum:
- limit_required
- invalid_cursor
- not_authed
- invalid_auth
- account_inactive
- no_permission
- invalid_arg_name
- invalid_array_arg
- invalid_charset
- invalid_form_data
- invalid_post_type
- missing_post_type
- team_added_to_org
- invalid_json
- json_not_object
- request_timeout
- upgrade_required
- fatal_error
ok:
$ref: '#/components/schemas/defs_ok_false'
additionalProperties: false
description: Schema for error response from users.list method
example:
error: invalid_cursor
ok: false
security:
- slackAuth:
- users:read
summary: Slack Get Users List
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users.lookupByEmail:
get:
tags:
- Get
- Users
description: Find a user with an email address.
externalDocs:
description: API method documentation
url: https://api.slack.com/methods/users.lookupByEmail
operationId: getUsersLookupbyemail
parameters:
- name: token
in: query
description: 'Authentication token. Requires scope: `users:read.email`'
required: true
schema:
type: string
- name: email
in: query
description: An email address belonging to a user in the workspace
required: true
schema:
type: string
responses:
'200':
description: Typical success response
content:
application/json:
schema:
title: users.lookupByEmail success schema
required:
- ok
- user
type: object
properties:
ok:
$ref: '#/components/schemas/defs_ok_true'
user:
$ref: '#/components/schemas/objs_user'
additionalProperties: true
description: Schema for successful response from users.lookupByEmail method
example:
ok: true
user:
color: 9f69e7
deleted: false
has_2fa: false
id: W012A3CDE
is_admin: true
is_app_user: false
is_bot: false
is_owner: false
is_primary_owner: false
is_restricted: false
is_ultra_restricted: false
name: spengler
profile:
avatar_hash: ge3b51ca72de
display_name: spengler
display_name_normalized: spengler
email: [email protected]
image_192: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_24: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_32: https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg
image_48: htt
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/slack/refs/heads/main/openapi/slack-users-openapi.yml