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

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.

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

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

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.

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

Collectibles Structure

Nameplate Data Structure

Nameplate Color Palette

Example Collectibles Object

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

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

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": []
}

Connection Object

The connection object that the user has attached.

Connection Structure

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

Partial Connection Structure

Example Connection

{
  "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": []
}

Example Partial Connection

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

Connection Integration Structure

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

Example Connection Integration

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

Connection Type

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

Visibility Type

Partial connections always have a visibility of 1.

Endpoints

Get Current User

Returns the user object of the requester's account.

Modify Current User

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 with the Get User Email Change Code endpoint and verifying it 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.

Modify Current User Account

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

JSON Params

Get Recent Avatars

Returns the user's recent avatars. For premium users, the six most recent avatars will be returned. Otherwise, only two will be returned.

Response Body

Avatar Structure

Example Response

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

Delete Recent Avatar

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

Get User

Returns a partial user object for a given user ID.

Get User Profile

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 an empty list / zero value 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
    }
  }
}

Modify User Profile

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

JSON Params

Get Mutual Relationships

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

Enable TOTP MFA

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

JSON Params

Response Body

Disable TOTP MFA

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

Response Body

Enable SMS MFA

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

Disable SMS MFA

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

JSON Params

Get WebAuthn Authenticators

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

Create WebAuthn Authenticator

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
    }
  ]
}

Modify WebAuthn Authenticator

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

JSON Params

Delete WebAuthn Authenticator

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

Send Backup Codes Challenge

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

Get Backup Codes

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
    }
  ]
}

Disable User

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

JSON Params

Delete User

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

JSON Params

Verify User Captcha

Verifies a reCAPTCHA solution when needed by the COMPLETE_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

Modify User Agreements

Reaffirms the user's agreements to Discord's Terms of Service and Privacy Policy when needed by the UPDATE_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

Get User Email Change Code

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

Verify User Email Change

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

JSON Params

Response Body

Get Pomelo Suggestions

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

Response Body

Example Response

{ "username": "gnarp.gnap" }

Get Pomelo Eligibility

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

JSON Params

Response Body

Example Response

{ "taken": true }

Create Pomelo Migration

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

JSON Params

Get Recent Mentions

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

Query String Params

Delete Recent Mention

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

Get User Harvest

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

Create User Harvest

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

JSON Params

¹ Invalid options are ignored. If the array contains no valid values, all data types are requested.

Harvest Backend Type

See the official support page for more information.

Get User Survey

Returns the current user's active survey.

Query String Params

¹ Only usable by Discord employees.

Response Body

Acknowledge User Survey

Marks a user survey as seen. Returns a 204 empty response on success.

Get User Notes

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

Example Response

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

Get User Note

Returns the note for the given user.

Response Body

Example Response

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