[Intro Slack API] webAPI category:users method:users.list

users.list API Overview

Function

Endpoint to get a list of users who have / have been in the past in the Slack workspace

how to use

endpoint url

https://slack.com/api/users.list

parameters

Argument

token

Must/ Optional

Must

Description

Authentication token bearing required scopes.

cursor

Optional

Paginate through collections of data by setting the cursorparameter to a next_cursorattribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection.

include_locale(ref 1)

Optional

Set this to true to receive the locale for users. Defaults to false

limit

Optional

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.

Reference 1：https://api.slack.com/changelog/2017-09-locale-locale-locale

HTTP method(preferred)

Get

Response

user object is replied(not ordered), actual sample as follow

{
    "ok": true,
    "members": [
        {
            "id": "W012A3CDE",
            "team_id": "T012AB3C4",
            "name": "spengler",
            "deleted": false,
            "color": "9f69e7",
            "real_name": "spengler",
            "tz": "America/Los_Angeles",
            "tz_label": "Pacific Daylight Time",
            "tz_offset": -25200,
            "profile": {
                "avatar_hash": "ge3b51ca72de",
                "status_text": "Print is dead",
                "status_emoji": ":books:",
                "real_name": "Egon Spengler",
                "display_name": "spengler",
                "real_name_normalized": "Egon Spengler",
                "display_name_normalized": "spengler",
                "email": "spengler@ghostbusters.example.com",
                "image_24": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "image_32": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "image_48": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "image_72": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "image_192": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "image_512": "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
                "team": "T012AB3C4"
            },
            "is_admin": true,
            "is_owner": false,
            "is_primary_owner": false,
            "is_restricted": false,
            "is_ultra_restricted": false,
            "is_bot": false,
            "updated": 1502138686,
            "is_app_user": false,
            "has_2fa": false
        },
        {
            "id": "W07QCRPA4",
            "team_id": "T0G9PQBBK",
            "name": "glinda",
            "deleted": false,
            "color": "9f69e7",
            "real_name": "Glinda Southgood",
            "tz": "America/Los_Angeles",
            "tz_label": "Pacific Daylight Time",
            "tz_offset": -25200,
            "profile": {
                "avatar_hash": "8fbdd10b41c6",
                "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_72": "https://a.slack-edge.com...png",
                "image_192": "https://a.slack-edge.com...png",
                "image_512": "https://a.slack-edge.com...png",
                "image_1024": "https://a.slack-edge.com...png",
                "image_original": "https://a.slack-edge.com...png",
                "first_name": "Glinda",
                "last_name": "Southgood",
                "title": "Glinda the Good",
                "phone": "",
                "skype": "",
                "real_name": "Glinda Southgood",
                "real_name_normalized": "Glinda Southgood",
                "display_name": "Glinda the Fairly Good",
                "display_name_normalized": "Glinda the Fairly Good",
                "email": "glenda@south.oz.coven"
            },
            "is_admin": true,
            "is_owner": false,
            "is_primary_owner": false,
            "is_restricted": false,
            "is_ultra_restricted": false,
            "is_bot": false,
            "updated": 1480527098,
            "has_2fa": false
        }
    ],
    "cache_ts": 1498777272,
    "response_metadata": {
        "next_cursor": "dXNlcjpVMEc5V0ZYTlo="
    }
}

Rough Explanation for Response users type（only major）

user.id

id of user each. this num set for everyone individually as identificator in slack

user.team_id

id of workspace. on API response, expressed as team that is old name of workspace. be carefull

user.name/ user.real_name

user.name == user.profile.display_name: name when mention to someone (@….）

user.real_name == user.profile.real_name: actual registration name

The two are basically same, however some case that have changed the display name (initial or just the name), which cause a difference between user.name and user.real_name.

user.deleted

Users who have / have been in the workspace and are currently out of the workspace. True if not (not affiliated), False if affiliated

As described at the very beginning of the “function” section, this is an API for requesting a list of users who have / have previously belonged to the Slack workspace, so the current affiliation status is displayed.

user.profile.image & user.profile.image_24/32/48/72/192/512

icon pict. “.image” is original pict. after image_24/… is the data for each resolution

is_admin/is_owner (such as is_ info)　

“is_” is response status that the user has rights or not by each category

Notes and Usage

regarding this endpoint, before checking reference, I think that the userlist api is extracting currently used (active) the user + bot, but in fact you can get a list of users + bot also who have registered in the past.

if you wanna use this endpoint as following purpose, do as:

Purpose: Get the currently active users (including bot)
Do: after getting response by JSON, extracting as user.deleted==false

Purpose: Make a list of retired employees (If you have not released Slack to anyone other than an employee such as a subcontractor, and all employees are registered as users)
Do: after getting response byJSON, extracting as “user.deleted==true” and “user.is_bot==false”