Users

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.

Usernames and Nicknames

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.

Unique Usernames

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.

Identifying 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.

Migrating

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.

Display Names

As part of unique usernames, 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.

Default Avatars

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.

User Object

User Structure

¹ 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.

⁵ Only included when when fetched from the Get Current User endpoint with with_analytics_token set to true.

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

Partial User Structure

¹ 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.

Primary Guild Structure

¹ This field is null when a user has not reaffirmed their identity after a tag change.

² Only populated for users with identity_enabled not set to false.

Premium State Structure

Premium Source

Premium Subscription Type

Premium Subscription Group Role

User Flags

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

Purchased Flags

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

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

Premium Type

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

Age Verification Status

Required Action Type

Denotes an action Discord requires the user to take before they can continue using the platform. In some cases, multiple actions may be required, and the user must complete all of them before they can continue using Discord.

Example User

{
  "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 not a bot!",
  "locale": "en-US",
  "nsfw_allowed": true,
  "mfa_enabled": true,
  "premium_type": 2,
  "avatar_decoration_data": {
    "sku_id": "1144058844004233369",
    "asset": "a_fed43ab12698df65902ba06727e20c0e",
    "expires_at": null
  },
  "email": "nelly@discord.com",
  "verified": true,
  "phone": "+18885940085",
  "authenticator_types": [1, 2, 3],
  "primary_guild": {
    "identity_guild_id": "80351110224678913",
    "identity_enabled": true,
    "tag": "MEOW",
    "badge": "7d1734ae5a615e82bc7a4033b98fade8"
  }
}

Example Partial User

{
  "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",
    "expires_at": null
  },
  "primary_guild": {
    "identity_guild_id": "80351110224678913",
    "identity_enabled": true,
    "tag": "MEOW",
    "badge": "7d1734ae5a615e82bc7a4033b98fade8"
  }
}

Avatar Decoration Data Object

A user's active avatar decoration.

Avatar Decoration Data Structure

Example Avatar Decoration Data

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

Collectibles Object

A user's equipped collectibles, excluding avatar decorations and profile effects.

Collectibles Structure

Nameplate Data Structure

Example Collectibles Object

{
  "nameplate": {
    "asset": "nameplates/nameplatetest/angel/",
    "palette": "bubble_gum",
    "label": "COLLECTIBLES_NAMEPLATETEST_ANGEL_A11Y",
    "sku_id": "1344802364934062152",
    "expires_at": null
  }
}

Display Name Style Object

How a user's name gets displayed, such as font, colors, gradient, glow.

Display Name Style Structure

Display Name Font

Display Name Effect

Game Widget Object

A tile on a user's profile showcasing their gaming interests.

Game Widget Data Structure

Game Widget Type

¹ Rendered as a detailed game widget in the user profile.

Game Widget Game Structure

Game Widget Tag

¹ Only one of these tags can be present in a game widget at a time.

Example Game Widget

{
  "id": "1455894303866880153",
  "updated_at": "2025-12-31T12:04:11.252336+00:00",
  "data": {
    "type": "favorite_games",
    "games": [
      {
        "game_id": "505134938354352128",
        "comment": "Best game ever!",
        "tags": ["expert", "open_to_teach"]
      }
    ]
  }
}

Profile Metadata Object

A user's profile metadata.

Profile Metadata Structure

¹ Not respected on guild profiles.

Profile Effect Structure

Example 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",
    "expires_at": 1740124800
  }
}

Authenticator Object

Authenticator Structure

Authenticator Type

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

Example Authenticator

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

Backup Code Object

A multi-factor authentication backup code.

Backup Code Structure

Example Backup Code

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

Harvest Object

A user's data harvest.

Harvest Structure

Example Harvest

{
  "harvest_id": "1319498748052639754",
  "user_id": "852892297661906993",
  "email": "alien@dolfi.es",
  "state": "DELIVERED",
  "status": 3,
  "created_at": "2024-12-20T02:56:56.639579+00:00",
  "completed_at": "2024-12-21T11:05:41.462828+00:00",
  "polled_at": "2024-12-21T11:05:41.462828+00:00",
  "backends": {
    "zendesk": "EXTRACTED",
    "ads": "EXTRACTED",
    "users": "EXTRACTED",
    "guilds": "EXTRACTED",
    "hubspot": "EXTRACTED",
    "messages": "EXTRACTED",
    "analytics": "EXTRACTED",
    "activities_e": "EXTRACTED",
    "activities_w": "EXTRACTED"
  },
  "updated_at": "2024-12-21T11:05:41.462828+00:00",
  "shadow_run": false,
  "harvest_metadata": {
    "user_is_staff": false,
    "sla_email_sent": false,
    "bypass_cooldown": false,
    "is_provisional": false
  }
}

Harvest Metadata Structure

Harvest State

Harvest Status

Harvest Backend Internal Type

Harvest Backend State

User Survey Object

A user survey.

User Survey Structure

Survey Requirement Type

Example User Survey

{
  "id": "1301267751645483122",
  "key": "1301267751645483122",
  "prompt": "Share your experience with Discord",
  "cta": "Take the survey!",
  "url": "https://discord.sjc1.qualtrics.com/jfe/form/SV_123456",
  "guild_requirements": [],
  "guild_size": [null, null],
  "guild_permissions": []
}

User Identity Verification Object

An Identity Verification used for application verification.

User Identity Verification Structure

¹ Only returned on newly-created identity verification attempts.

User Identity Verification Status

User Identity Verification Error

Endpoints

Returns the user object of the requester's account.

Query String Params

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

JSON Params

¹ 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 as outlined in the email verification documentation.

⁵ If using unique usernames, 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 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 information on username restrictions.

⁶ VOIP-specific push notification tokens are only used with PushKit on iOS.

Modifies the requester's user account settings. Returns a partial user object on success. Fires a User Update Gateway event.

JSON Params

Returns the user's 6 most recent avatars.

Response Body

Avatar Structure

Example Response

{
  "avatars": [
    {
      "id": "1357011390585507910",
      "storage_hash": "212aed0ac14cf7804051218f99624a9f",
      "description": "alien, added April 2, 2025 at 5:09 PM"
    }
  ]
}

Deletes a recent avatar for the user. Returns a 204 empty response on success.

Returns a partial user object for a given user ID.

Returns a user profile object for a given user ID.

Query String Params

Response Body

¹ 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.

³ This will always be empty for bots, even if the user has mutual friends with it.

Profile Application Structure

Profile Badge Structure

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

Mutual Guild Structure

Example Response

{
  "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,
    "primary_guild": 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,
    "unusual_dm_activity_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,
      "primary_guild": 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",
      "expires_at": null
    }
  },
  "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",
      "expires_at": null
    }
  }
}

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

JSON Params

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

Replaces the user's profile widgets, and returns a list of game widget which has been put on the user's profile.

JSON Params

¹ The id field is optional and updated_at is ignored.

Returns suggested applications for the current user's profile game widgets.

Response Body

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

JSON Params

Response Body

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

Response Body

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.

JSON Params

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

JSON Params

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.

JSON Params

Response Body

¹ Only returned when no parameters are provided.

² Only returned when parameters are provided.

Example Response (Ticket)

{
  "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\"}}"
}

Example Response (Authenticator)

{
  "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.

JSON Params

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.

JSON Params

Response Body

Returns the user's MFA backup codes.

JSON Params

¹ 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.

Response Body

Example Response

{
  "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.

JSON Params

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

JSON Params

Verifies a reCAPTCHA solution when needed by the REQUIRE_CAPTCHA required action. Returns a 204 empty response on success. Fires a User Required Action Update Gateway event.

reCAPTCHA Site Key

6Lef5iQTAAAAAKeIvIY-DeexoO3gj7ryl9rLMEnn

JSON Params

Reaffirms the user's agreements to Discord's Terms of Service and Privacy Policy when needed by the AGREEMENTS required action, which is assigned when a policy change occurs. Returns a 204 empty response on success. Fires a User Required Action Update Gateway event.

JSON Params

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

Response Body

Example Response

{ "username": "gnarp.gnap" }

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

JSON Params

Response Body