Users Resource

Users in Discord are generally considered the base entity. Users can spawn across the entire platform, be members of guilds, participate in text and voice chat, and much more. Users are separated by a distinction of "bot" vs "normal". Although they are similar, bot users are automated users that are attached to an application, "owned" by another user. Unlike normal users, bot users do not have a limitation on the number of guilds they can be a part of.

Discord enforces the following restrictions for usernames, display names, and nicknames:

1. Names can contain most valid unicode characters. We limit some zero-width and non-rendering characters.
2. Usernames must be between 2 and 32 characters long.
3. Display names and nicknames must be between 1 and 32 characters long.
4. Webhook names must be between 1 and 80 characters long.
5. Names are sanitized and trimmed of leading, trailing, and excessive internal whitespace.

The following restrictions are additionally enforced for usernames and display names:

1. Usernames cannot contain the following substrings: '@', '#', ':', '```'.
2. Usernames and display names cannot be: 'everyone', 'here', 'system message', or contain 'discord'.

The following restrictions are additionally enforced for webhook names:

1. Webhook names cannot contain the following substrings: 'clyde'.

Migrated usernames are subject to a new set of restrictions in addition to the above:

1. Migrated usernames can only contain lowercase alphanumeric characters, underscores (_), and periods (.). Uppercase characters, spaces, dashes (-), and other special characters are not allowed.
2. Migrated usernames cannot have two or more consecutive periods (..).
3. Migrated usernames are unique to each user, and no two users can share the same username.

There are other rules and restrictions not shared here for the sake of spam and abuse mitigation, but the majority of users won't encounter them. It's important to properly handle all error messages returned by Discord when editing or updating names.

Discord's username system is changing. Discriminators are being removed and new, unique usernames (@name) and display names are being introduced. Internally, this migration is referred to as "pomelo". You can read more details about how the changes to the username system affect user accounts in the general Help Center article. To learn how it impacts bots specifically, you can read the Developer Help Center article.

A user's legacy username#discriminator tag will still be usable to send friend requests, and will be available as a profile badge for migrated users.

The value of a single zero (0) in the discriminator field on the user object indicates that the user has been pommeled migrated to the new username system. Note that the discriminator for migrated users will not be 4-digits like a standard discriminator (it is 0, not 0000). The value of the username field will become the migrated user's unique username.

Users can only migrate their account to pomelo if they are in the rollout. A user is in the rollout if they have pomelo in the disclose field on the Ready Supplemental event and are in the 2023-03_pomelo user experiment. Migration is now complete and all non-migrated users have been automatically assigned a unique username.

To migrate, users should first check if the username they want is available, and then migrate their account to that username. If the username they want is not available, they can get a list of suggested usernames to choose from.

As part of pomelo, user accounts can define a non-unique display name. This value is a new nullable global_name field with a max length of 32 characters.

For bots, the display name will be the same as their application's name.

For users with migrated accounts, default avatar URLs will be based on the user ID instead of the discriminator. The URL can be calculated using (user_id >> 22) % 6. For non-migrated accounts, the URL can be calculated using discriminator % 5.

¹ Not included when fetching a user via OAuth2.

² Not included when fetching a user via OAuth2 without the email scope.

³ Not included in the user object returned in the Ready event.

⁴ Only included in the user object returned in the Ready event.

⁵ See the section on Discord's new username system for more information.

¹ See the section on Discord's new username system for more information.

² Only guaranteed to be included when fetched through the Get User and Get User Profile endpoints. May be included in data received through other API endpoints.

³ Only guaranteed to be included when fetched through the Get User endpoint or the author field on the message object. May be included in data received through other API endpoints.

¹ Only populated for users with identity_enabled set to true.

{
  "id": "80351110224678912",
  "username": "nelly",
  "global_name": "Nelly",
  "avatar": "8342729096ea3675442027381ff50dfe",
  "discriminator": "0",
  "public_flags": 64,
  "flags": 96,
  "purchased_flags": 10,
  "premium_usage_flags": 4,
  "banner": "06c16474723fe537c283b8efa61a30c8",
  "accent_color": null,
  "bio": "I'm a bot!",
  "locale": "en-US",
  "nsfw_allowed": true,
  "mfa_enabled": true,
  "premium_type": 2,
  "avatar_decoration_data": {
    "sku_id": "1144058844004233369",
    "asset": "a_fed43ab12698df65902ba06727e20c0e"
  },
  "email": "nelly@discord.com",
  "verified": true,
  "phone": "+18885940085",
  "authenticator_types": [1, 2, 3],
  "clan": {
    "identity_guild_id": "80351110224678913",
    "identity_enabled": true,
    "tag": "MEOW",
    "badge": "7d1734ae5a615e82bc7a4033b98fade8"
  }
}

{
  "id": "80351110224678912",
  "username": "nelly",
  "avatar": "8342729096ea3675442027381ff50dfe",
  "discriminator": "0",
  "public_flags": 64,
  "banner": "06c16474723fe537c283b8efa61a30c8",
  "accent_color": 16711680,
  "global_name": "Nelly",
  "avatar_decoration_data": {
    "sku_id": "1144058844004233369",
    "asset": "a_fed43ab12698df65902ba06727e20c0e"
  },
  "clan": {
    "identity_guild_id": "80351110224678913",
    "identity_enabled": true,
    "tag": "MEOW",
    "badge": "7d1734ae5a615e82bc7a4033b98fade8"
  }
}

¹ Not exposed to the API, can only be found in user data harvests.

Purchased flags denote what premium items a user has ever purchased. Visit the Nitro page to learn more about the premium plans currently offered.

Premium usage flags denote what premium (Nitro) features a user has utilized.

Premium types denote the level of premium a user has. Visit the Nitro page to learn more about the premium plans currently offered.

Required action types denote an action Discord requires the user to take before they can continue using the platform.

¹ This is now represented by first receiving a VERIFY_PHONE action, and then receiving a VERIFY_EMAIL action after the phone number has been verified.

The client theme denotes the theme the user has set in their client.

A user's active avatar decoration.

{
  "sku_id": "1144058844004233369",
  "asset": "a_fed43ab12698df65902ba06727e20c0e"
}

A user's profile metadata.

{
  "guild_id": "80351110224678913",
  "pronouns": "gnarp/gnap",
  "bio": "👽 Professional alien",
  "banner": null,
  "accent_color": null,
  "theme_colors": [1, 1],
  "popout_animation_particle_type": null,
  "emoji": {
    "name": "meowlien",
    "roles": [],
    "id": "1090395834966880336",
    "require_colons": true,
    "managed": false,
    "animated": false,
    "available": true
  },
  "profile_effect": {
    "id": "1139323097930027068"
  }
}

Authenticator types represent enabled multi-factor authentication methods. See the MFA verification documentation for more information.

{
  "id": "1219430671865610261",
  "type": 1,
  "name": "AlienKey"
}

A multi-factor authentication backup code.

{
  "user_id": "852892297661906993",
  "code": "zqs8oqxk",
  "consumed": false
}

A user's data harvest.

{
  "harvest_id": "1069316408502124624",
  "user_id": "852892297661906993",
  "status": 3,
  "created_at": "2023-01-29T18:01:38.730771+00:00",
  "completed_at": "2023-02-01T08:29:03.680228+00:00",
  "polled_at": "2023-02-01T08:29:03.680228+00:00"
}

The connection object that the user has attached.

¹ Not included when fetching a user's connections via OAuth2.

² These integrations can be used to join your own sub-enabled guild or the guild of a creator you are supporting.

{
  "type": "reddit",
  "id": "run&hide",
  "name": "alien",
  "visibility": 1,
  "friend_sync": false,
  "show_activity": true,
  "verified": true,
  "two_way_link": false,
  "metadata_visibility": 1,
  "metadata": {
    "gold": "0",
    "mod": "1",
    "total_karma": "20223",
    "created_at": "2019-05-02T20:28:37"
  },
  "revoked": false,
  "integrations": []
}

{
  "type": "reddit",
  "id": "run&hide",
  "name": "alien",
  "verified": true,
  "metadata": {
    "gold": "0",
    "mod": "1",
    "total_karma": "20223",
    "created_at": "2019-05-02T20:28:37"
  }
}

¹ This field may also be the literal string "twitch-partners" to represent the Twitch Partners integration.

{
  "id": "twitch-partners",
  "type": "twitch",
  "account": {
    "id": "92473777",
    "name": "discordapp"
  },
  "guild": {
    "id": "107939014299901952",
    "name": "Twitch Partners",
    "icon": "62450d21b75478191962d9c4b81831ae"
  }
}

¹ Service can no longer be added by users.

² Service is not returned in Get User Profile or when fetching a user's connections via OAuth2.

Partial connections always have a visibility of 1.

A relationship between the current user and another user.

{
  "id": "852892297661906993",
  "type": 3,
  "nickname": null,
  "user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "14733482e560d9267c0a414b21b2fb8d",
    "discriminator": "0",
    "public_flags": 64,
    "avatar_decoration_data": null
  },
  "since": "2023-02-10T01:58:05.348000+00:00"
}

A friend suggestion for the current user.

{
  "suggested_user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "14733482e560d9267c0a414b21b2fb8d",
    "discriminator": "0",
    "public_flags": 64,
    "avatar_decoration_data": null
  },
  "reasons": [
    {
      "type": 1,
      "platform_type": "contacts",
      "name": "Gnarpy"
    }
  ]
}

Returns the user object of the requester's account.

Modifies the requester's user account settings. Returns a user object with an extra token key representing the user's new authorization token on success. Fires a User Update Gateway event.

¹ Required for changing username, discriminator, email, date_of_birth, or new_password.

² Setting this defines the nsfw_allowed field of the user based on whether they are over 18.

³ Changing the account password invalidates all active tokens. Don't fret though, as the token key in the response will be valid.

⁴ This value can be obtained by requesting a verification code with the Modify User Email endpoint, and then using the Verify User Email Change endpoint.

⁵ If using pomelo, the username field must be unique across Discord, and discriminator cannot be changed. Else, the username and discriminator fields must be unique across Discord, and changing the username changed may cause the discriminator to be randomized. See the section on Discord's new username system for more information. See the Usernames and Nicknames section for more information on username restrictions.

Returns a partial user object for a given user ID.

Returns a partial user object for a given username.

¹ See the section on Discord's new username system for more information.

Returns a user profile object for a given user ID.

¹ These fields are unexpectedly missing or null if the user has blocked the current user.

² See the section on Discord's new username system for more information.

For a list of known profile badges, refer to this Gist.

{
  "user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "9d52298a3ad006da31ac66a86230d9f2",
    "avatar_decoration_data": null,
    "discriminator": "0",
    "public_flags": 64,
    "flags": 64,
    "banner": "a_17a0757cf6121ccc07546de9bff3edb2",
    "accent_color": null,
    "bio": "👽 Professional smoothbrain",
    "avatar_decoration_data": null
  },
  "connected_accounts": [
    {
      "type": "twitter",
      "id": "123456",
      "name": "discord",
      "verified": true,
      "metadata": {
        "verified": "1",
        "followers_count": "100000",
        "statuses_count": "100000",
        "created_at": "2016-01-01T00:00:00"
      }
    }
  ],
  "premium_since": "2016-01-01T00:00:00.00+00:00",
  "premium_type": 2,
  "premium_guild_since": "2016-01-01T00:00:00.00+00:00",
  "mutual_friends_count": 100,
  "mutual_guilds": [
    {
      "id": "80351110224678913",
      "nick": "Liena"
    }
  ],
  "guild_member": {
    "avatar": null,
    "communication_disabled_until": null,
    "flags": 0,
    "joined_at": "2016-01-01T00:00:00.00+00:00",
    "nick": null,
    "pending": false,
    "premium_since": "2016-01-01T00:00:00.00+00:00",
    "roles": [],
    "user": {
      "id": "852892297661906993",
      "username": "alien",
      "global_name": "Alien",
      "avatar": "9d52298a3ad006da31ac66a86230d9f2",
      "discriminator": "0",
      "public_flags": 4194368,
      "avatar_decoration_data": null
    },
    "bio": "👽 Professional alien",
    "banner": null,
    "mute": false,
    "deaf": false
  },
  "application_role_connections": [
    {
      "platform_name": "Aliens United",
      "platform_username": "Alien",
      "metadata": {
        "real": "1",
        "certified": "1"
      },
      "application": {
        "id": "891436233903964161",
        "name": "Lightbulb",
        "icon": "4d47160ec8c45f22e2bdbe75ac3e1bbd",
        "description": "<:support_icon:853084466016288828> Imagine a bot.",
        "summary": "",
        "type": null,
        "bot": {
          "id": "891436233903964161",
          "username": "lightbulb",
          "global_name": "Lightbulb",
          "avatar": "59fb354bf144ed784aa8bdef88d135bb",
          "avatar_decoration_data": null,
          "discriminator": "0",
          "public_flags": 0,
          "bot": true
        }
      },
      "application_metadata": {
        "real": {
          "type": 7,
          "key": "real",
          "name": "Real",
          "description": "Are you real alier?"
        },
        "certified": {
          "type": 7,
          "key": "certified",
          "name": "Certified",
          "description": "Are you certified alier?"
        }
      }
    }
  ],
  "user_profile": {
    "bio": "👽 Professional smoothbrain",
    "accent_color": null,
    "pronouns": "gnarp/gnap",
    "banner": "a_17a0757cf6121ccc07546de9bff3edb2",
    "theme_colors": [1, 1],
    "popout_animation_particle_type": 100000,
    "emoji": null,
    "profile_effect": {
      "id": "1139323097930027068"
    }
  },
  "guild_member_profile": {
    "guild_id": "80351110224678913",
    "pronouns": "",
    "bio": "👽 Professional alien",
    "banner": null,
    "accent_color": null,
    "theme_colors": [1, 1],
    "popout_animation_particle_type": null,
    "emoji": null,
    "profile_effect": {
      "id": "1139323097930027068"
    }
  }
}

Returns a list of games the user has played in the last week.

{
  "recent_games": [
    {
      "application": {
        "id": "356888577310851072",
        "name": "Team Fortress 2",
        "icon": "dfc652a5b75879148779dc2865270f87",
        "description": "The long-awaited sequel to the class-based first-person shooter Team Fortress Classic sports a unique cartoony visual style, more accessible gameplay, and a very large amount of updates and new features since its original release.",
        "type": 1,
        "summary": "",
        "splash": "a109376e705e71ab44e7d2d966cecc35",
        "third_party_skus": [
          {
            "id": "440",
            "sku": "440",
            "distributor": "steam"
          }
        ],
        "is_monetized": false
      },
      "duration": 1337,
      "last_session_id": "1234563653992833025",
      "is_new": false
    }
    {
      "application": {
        "id": "1121201675240210523",
        "name": "Honkai: Star Rail",
        "icon": "444d067889922e42b0af99b13e5d5c72",
        "description": "",
        "type": 1,
        "bot": {
          "id": "1121201675240210523",
          "username": "Honkai Star Rail",
          "avatar": "444d067889922e42b0af99b13e5d5c72",
          "discriminator": "8967",
          "public_flags": 0,
          "bot": true,
          "banner": null,
          "accent_color": null,
          "global_name": null,
          "avatar_decoration_data": null
        },
        "summary": "",
        "is_monetized": false
      },
      "duration": 2560,
      "last_session_id": "1234175874748911658",
      "is_new": false
    }
  ]
}

Modifies the current user's profile. Returns the updated profile metadata object on success. Fires a User Update Gateway event.

Returns a list of partial user objects that are friends with the user and current user.

Enables TOTP multi-factor authentication for the current user. Fires a User Update Gateway event.

Disables TOTP multi-factor authentication for the current user. Fires a User Update Gateway event.

Enables SMS multi-factor authentication for the current user. Requires that TOTP-based MFA is already enabled and the user has a verified phone number. Returns a 204 empty response on success. Fires a User Update Gateway event.

Disables SMS multi-factor authentication for the current user. Returns a 204 empty response on success. Fires a User Update Gateway event.

Returns a list of WebAuthn authenticator objects for the current user.

Creates a WebAuthn authenticator for the current user. Fires User Update and Authenticator Create Gateway events once the authenticator is created.

¹ Only returned when no parameters are provided.

² Only returned when parameters are provided.

{
  "ticket": "ODUyODkyMjk3NjYxOTA2OTkz.H2Rpq0.WrhGhYEhM3lHUPN61xF6JcQKwVutk8fBvcoHjo",
  "challenge": "{\"publicKey\":{\"challenge\":\"a8a1cHP7_zYheggFG68zKUkl8DwnEqfKvPE-GOMvhss\",\"timeout\":60000,\"rpId\":\"discord.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":\"izrvF80ogrfg9dC3RmWWwW1VxBVBG0TzJVXKOJl__6FvMa555dH4Trt2Ub8AdHxNLkQsc0unAGcn4-hrJHDKSO\"}],\"userVerification\":\"preferred\"}}"
}

{
  "id": "1219430671865610261",
  "type": 1,
  "name": "AlienKey",
  "backup_codes": [
    {
      "user_id": "852892297661906993",
      "code": "zqs8oqxk",
      "consumed": false
    }
  ]
}

Modifies the given WebAuthn authenticator. Returns the updated authenticator object on success. Fires an Authenticator Update Gateway event.

Deletes the given WebAuthn authenticator. Returns a 204 empty response on success. Fires User Update and Authenticator Delete Gateway events.

Sends an email to the current user with a verification code that allows them to view their backup codes. Returns a 204 empty response on success.

Returns the user's MFA backup codes.

¹ This value can be obtained by requesting a verification code with the Send Backup Codes Challenge endpoint.

² The nonce used must correspond to the action being performed. Each action can only be performed once.

{
  "backup_codes": [
    {
      "user_id": "852892297661906993",
      "code": "zqs8oqxk",
      "consumed": false
    }
  ]
}

Disables the current user's account. Invalidates all active tokens. Returns a 204 empty response on success.

Marks the current user's account for deletion. Invalidates all active tokens. Returns a 204 empty response on success.

Verifies a reCAPTCHA solution when required for verification. Returns a 204 empty response on success. Fires a User Required Action Update Gateway event.

6Lef5iQTAAAAAKeIvIY-DeexoO3gj7ryl9rLMEnn

Sends a verification email to the current user's email address to initiate the email change process. Returns a 204 empty response on success.

Verifies a verification code sent to the current user's email address to initiate an email change.

Returns a suggested unique username string based on the current user's username.

{ "username": "gnarp.gnap" }

Checks whether a unique username is available for the user to claim.

{ "taken": true }

Claims a unique username for the user. Returns the updated user object on success. Fires a User Update Gateway event.

Returns a list of message objects that the current user has been mentioned in during the past 7 days.

Acknowledges a message the current user has been mentioned in. Returns a 204 empty response on success. Fires a Recent Mention Delete Gateway event.

If it exists, returns a harvest object representing the current user's most recent personal data harvest request. Otherwise, returns a 204 empty response.

Creates a personal data harvest request for the current user. Returns a harvest object on success.

¹ Invalid options are ignored. If the array is empty after this, it requests all data types.

See the official support page for more information.

Returns a mapping of user IDs to notes for the current user.

{
  "852892297661906993": "This is a note",
  "787017887877169173": "This is another note"
}

Returns the note for the given user.

{
  "note": "This is a note",
  "note_user_id": "787017887877169173",
  "user_id": "852892297661906993"
}

Sets the note for the given user. Returns a 204 empty response on success. Fires a User Note Update Gateway event.

Returns an authorization link that can be used for authorizing a new connection.

Creates a new connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

Creates a new contact sync connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

Creates a new domain connection for the current user. Returns a connection object on success. Fires a User Connections Update Gateway event.

Returns a list of connection objects.

Returns a new access token for the given connection. Only available for Twitch, YouTube, and Spotify connections. Fires a User Connections Update Gateway event.

Returns a list of subreddits the connected account moderates. Only available for Reddit connections.

[
  {
    "id": "t5_388p4",
    "subscribers": 1044184,
    "url": "/r/discordapp/"
  }
]

Refreshes a connection. Returns a 204 empty response on success. Fires a User Connections Update Gateway event.

Modifies a connection. Returns a connection object on success. Fires a User Connections Update Gateway event.

Not all connection types support all parameters.

Deletes a connection. Returns a 204 empty response on success. Fires a User Connections Update and may fire a Guild Delete Gateway event.

Returns a list of relationship objects for the current user.

¹ Only usable with OAuth2 requests. On non-OAuth2 requests, only user-created relationships will be returned.

Sends a friend request to another user, which can be accepted by creating a new relationship of type FRIEND. Returns a 204 empty response on success. Fires a Relationship Add Gateway event.

¹ null for migrated users. See the section on Discord's new username system for more information.

Creates a relationship with another user. Returns a 204 empty response on success. Fires a Relationship Add Gateway event.

Modifies a relationship to another user. Returns a 204 empty response on success. Fires a Relationship Update Gateway event.

¹ Only applicable to relationships of type FRIEND.

Removes a relationship with another user. Returns a 204 empty response on success. Fires a Relationship Remove Gateway event.

Returns a list of friend suggestion objects for the current user.

Removes a friend suggestion for the current user. Returns a 204 empty response on success. Fires a Friend Suggestion Delete Gateway event.

Returns the current user's affinity scores for other users. Affinity scores are a measure of how likely a user is to be friends with another user.

Returns the current user's affinity scores for their joined guilds.

Returns the current user's remaining burst credits. Burst credits are used to create burst reactions.

Returns the current user's premium usage for various perks. Only available for users with Nitro.

{
  "total_large_uploads": {
    "value": 50
  },
  "total_global_emojis": {
    "value": 967
  },
  "total_animated_emojis": {
    "value": 217
  },
  "nitro_sticker_sends": {
    "value": 303
  },
  "hd_hours_streamed": {
    "value": 100
  },
  "total_hd_streams": {
    "value": 50
  }
}

Returns the list of profile effects available to use.

{
  "profile_effect_configs": [
    {
      "type": 1,
      "id": "1139323075519852625",
      "sku_id": "1139323092645183591",
      "title": "Hydro Blast",
      "description": "Time to make a splash.",
      "accessibilityLabel": "A powerful stream of water swirls and twirls in the air. Wait, where's it headed off to?!",
      "animationType": 2,
      "thumbnailPreviewSrc": "https://cdn.discordapp.com/assets/profile_effects/effects/b17d139f2e9/splash/thumbnail.png",
      "reducedMotionSrc": "https://cdn.discordapp.com/assets/profile_effects/effects/b17d139f2e9/splash/reducedMotion.png",
      "effects": [
        {
          "src": "https://cdn.discordapp.com/assets/profile_effects/effects/b17d139f2e9/splash/intro.png",
          "loop": false,
          "height": 880,
          "width": 450,
          "duration": 2880,
          "start": 0,
          "loopDelay": 0,
          "position": {
            "x": 0,
            "y": 0
          },
          "zIndex": 100
        },
        {
          "src": "https://cdn.discordapp.com/assets/profile_effects/effects/b17d139f2e9/splash/loop.png",
          "loop": true,
          "height": 880,
          "width": 450,
          "duration": 2880,
          "start": 5760,
          "loopDelay": 5760,
          "position": {
            "x": 0,
            "y": 0
          },
          "zIndex": 100
        }
      ]
    }
  ]
}