Invite Resource

Invite Object

Represents a code that when used, adds a user to a guild or group DM channel.

Invite Structure

Field	Type	Description
type	integer	the type of invite
code	string	the invite code (unique ID)
guild?	partial guild object	the guild this invite is for
channel	?partial channel object	the channel this invite is for
inviter?	user object	the user who created the invite
target_type?	integer	the type of target for this voice channel invite
target_user?	user object	the user whose stream to display for this voice channel stream invite
target_application?	partial application object	the embedded application to open for this voice channel embedded application invite
approximate_presence_count?	integer	approximate count of online members, returned from the `GET /invites/<code>` endpoint when `with_counts` is `true`
approximate_member_count?	integer	approximate count of total members, returned from the `GET /invites/<code>` endpoint when `with_counts` is `true`
expires_at	?ISO8601 timestamp	the expiration date of this invite
guild_scheduled_event?	guild scheduled event object	guild scheduled event data, only included if `guild_scheduled_event_id` contains a valid guild scheduled event id
flags?	integer	guild invite flags for guild invites
roles?*	array of partial role objects	the roles assigned to the user upon accepting the invite.

* This is a partial role object that only contains id, name, position, color, colors, icon, and unicode_emoji.

Invite Types

Type	Value
GUILD	0
GROUP_DM	1
FRIEND	2

Invite Target Types

Type	Value
STREAM	1
EMBEDDED_APPLICATION	2

Guild Invite Flags

Flag	Value	Description
IS_GUEST_INVITE	`1 << 0`	this invite is a guest invite for a voice channel

Example Invite Object

{
  "type": 0,
  "code": "0vCdhLbwjZZTWZLD",
  "guild": {
    "id": "165176875973476352",
    "name": "CS:GO Fraggers Only",
    "splash": null,
    "banner": null,
    "description": "Very good description",
    "icon": null,
    "features": ["NEWS", "DISCOVERABLE"],
    "verification_level": 2,
    "vanity_url_code": null,
    "nsfw_level": 0,
    "premium_subscription_count": 5
  },
  "channel": {
    "id": "165176875973476352",
    "name": "illuminati",
    "type": 0
  },
  "inviter": {
    "id": "115590097100865541",
    "username": "speed",
    "avatar": "deadbeef",
    "discriminator": "7653",
    "public_flags": 131328
  },
  "target_type": 1,
  "target_user": {
    "id": "165176875973476352",
    "username": "bob",
    "avatar": "deadbeef",
    "discriminator": "1234",
    "public_flags": 64
  }
}

Invite Metadata Object

Extra information about an invite, will extend the invite object.

Invite Metadata Structure

Field	Type	Description
uses	integer	number of times this invite has been used
max_uses	integer	max number of times this invite can be used
max_age	integer	duration (in seconds) after which the invite expires
temporary	boolean	whether this invite only grants temporary membership
created_at	ISO8601 timestamp	when this invite was created

Example Invite Metadata

{
  "uses": 0,
  "max_uses": 0,
  "max_age": 0,
  "temporary": false,
  "created_at": "2016-03-31T19:15:39.954000+00:00"
}

Invite Stage Instance Object

This is deprecated.

Invite Stage Instance Structure

Field	Type	Description
members	array of partial guild member objects	the members speaking in the Stage
participant_count	integer	the number of users in the Stage
speaker_count	integer	the number of users speaking in the Stage
topic	string	the topic of the Stage instance (1-120 characters)

Example Invite Stage Instance

{
  "topic": "The debate is over: diet is better than regular",
  "participant_count": 200,
  "speaker_count": 5 ,
  "members": [
    {
      "roles": [],
      "nick": "NOT API SUPPORT",
      "avatar": null,
      "premium_since": null,
      "joined_at": "2015-04-26T06:26:56.936000+00:00",
      "pending": false,
      "user": {}
    }
  ]
}

Get Invite

Returns an invite object for the given code.

Query String Params

Field	Type	Description
with_counts?	boolean	whether the invite should contain approximate member counts
guild_scheduled_event_id?	snowflake	the guild scheduled event to include with the invite

Delete Invite

Delete an invite. Requires the MANAGE_CHANNELS permission on the channel this invite belongs to, or MANAGE_GUILD to remove any invite across the guild. Returns an invite object on success. Fires an Invite Delete Gateway event.

This endpoint supports the X-Audit-Log-Reason header.

Get Target Users

Gets the users allowed to see and accept this invite. Response is a CSV file with the header user_id and each user ID on its own line. Requires the caller to be the inviter, or have MANAGE_GUILD permission, or have VIEW_AUDIT_LOG permission.

Add Target User

Adds a target user to an existing invite. Requires the caller to be the inviter or have the MANAGE_GUILD permission. Returns a 204 empty response on success.

Remove Target User

Removes a target user from an existing invite. Requires the caller to be the inviter or have the MANAGE_GUILD permission. Returns a 204 empty response on success.

Update Target Users

Updates the users allowed to see and accept this invite. Uploading a file with invalid user IDs will result in a 400 with the invalid IDs described. Requires the caller to be the inviter or have the MANAGE_GUILD permission.

Form Params

Field	Type	Description
target_users_file	file	a csv file with a single column of user IDs for all the users able to accept this invite

Example Error Response

{
  "target_users_file": [
    "Line 5: invalid user ID - must be a valid Discord snowflake",
    "Line 6: invalid user ID format"
  ]
}

Bulk-Add Target Users

Adds multiple target users to an existing invite. Requires the caller to be the inviter or have the MANAGE_GUILD permission. Returns a 204 empty response on success.

JSON Params

Field	Type	Description
user_ids	array of snowflakes	the IDs of users to add, max of 1000 users

Bulk-Delete Target Users

Removes multiple target users from an existing invite. Requires the caller to be the inviter or have the MANAGE_GUILD permission. Returns a 204 empty response on success.

JSON Params

Field	Type	Description
user_ids	array of snowflakes	the IDs of users to remove, max of 1000 users

Get Target Users Job Status

Processing target users from a CSV when creating or updating an invite is done asynchronously. This endpoint allows you to check the status of that job. Requires the caller to be the inviter, or have MANAGE_GUILD permission, or have VIEW_AUDIT_LOG permission.

Example Response

{
  "status": 3,
  "total_users": 100,
  "processed_users": 41,
  "created_at": "2025-01-08T12:00:00.000000+00:00",
  "completed_at": null,
  "error_message": "Failed to parse CSV file"
}

Status Codes

Code	Name	Description
0	UNSPECIFIED	The default value.
1	PROCESSING	The job is still being processed.
2	COMPLETED	The job has been completed successfully.
3	FAILED	The job has failed, see `error_message` field for more details.

API Reference

SDK Reference

HTTP API Resources

Events

Voice & RPC

Invite Object

Invite Structure

Invite Types

Invite Target Types

Guild Invite Flags

Example Invite Object

Invite Metadata Object

Invite Metadata Structure

Example Invite Metadata

Invite Stage Instance Object

Invite Stage Instance Structure

Example Invite Stage Instance

Get Invite

Query String Params

Delete Invite

Get Target Users

Add Target User

Remove Target User

Update Target Users

Form Params

Example Error Response

Bulk-Add Target Users

JSON Params

Bulk-Delete Target Users

JSON Params

Get Target Users Job Status

Example Response

Status Codes

​Invite Object

Invite Structure

Invite Types

Invite Target Types

Guild Invite Flags

Example Invite Object

​Invite Metadata Object

Invite Metadata Structure

Example Invite Metadata

​Invite Stage Instance Object

Invite Stage Instance Structure

Example Invite Stage Instance

​Get Invite

Query String Params

​Delete Invite

​Get Target Users

​Add Target User

​Remove Target User

​Update Target Users

Form Params

Example Error Response

​Bulk-Add Target Users

JSON Params

​Bulk-Delete Target Users

JSON Params

​Get Target Users Job Status

Example Response

Status Codes

Invite Object

Invite Metadata Object

Invite Stage Instance Object

Get Invite

Delete Invite

Get Target Users

Add Target User

Remove Target User

Update Target Users

Bulk-Add Target Users

Bulk-Delete Target Users

Get Target Users Job Status