Invite Resource
Invite Object
Section titled “Invite Object”Represents a code that when used, adds a user to a guild or group DM channel.
Invite Structure
Section titled “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
Section titled “Invite Types”| Type | Value |
|---|---|
| GUILD | 0 |
| GROUP_DM | 1 |
| FRIEND | 2 |
Invite Target Types
Section titled “Invite Target Types”| Type | Value |
|---|---|
| STREAM | 1 |
| EMBEDDED_APPLICATION | 2 |
Guild Invite Flags
Section titled “Guild Invite Flags”| Flag | Value | Description |
|---|---|---|
| IS_GUEST_INVITE | 1 << 0 |
this invite is a guest invite for a voice channel |
Example Invite Object
Section titled “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
Section titled “Invite Metadata Object”Extra information about an invite, will extend the invite object.
Invite Metadata Structure
Section titled “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
Section titled “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
Section titled “Invite Stage Instance Object”Invite Stage Instance Structure
Section titled “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
Section titled “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
Section titled “Get Invite”/invites/{invite.code}
Returns an invite object for the given code.
Query String Params
Section titled “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
Section titled “Delete Invite”/invites/{invite.code}
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.
Get Target Users
Section titled “Get Target Users”/invites/{invite.code}/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
Section titled “Add Target User”/invites/{invite.code}/target-users/{user.id}
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
Section titled “Remove Target User”/invites/{invite.code}/target-users/{user.id}
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
Section titled “Update Target Users”/invites/{invite.code}/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
Section titled “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
Section titled “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
Section titled “Bulk-Add Target Users”/invites/{invite.code}/target-users/bulk-add
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
Section titled “JSON Params”| Field | Type | Description |
|---|---|---|
| user_ids | array of snowflakes | the IDs of users to add, max of 1000 users |
Bulk-Delete Target Users
Section titled “Bulk-Delete Target Users”/invites/{invite.code}/target-users/bulk-delete
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
Section titled “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
Section titled “Get Target Users Job Status”/invites/{invite.code}/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
Section titled “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
Section titled “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. |