Skip to main content

​
Invite object

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

​
Invite structure

​
type
integer
required
The type of invite.
​
code
string
required
The invite code (unique ID).
​
guild
partial guild object
The guild this invite is for. Optional field.
​
channel
?partial channel object
required
The channel this invite is for. Can be null.
​
inviter
user object
The user who created the invite. Optional field.
​
target_type
integer
The type of target for this voice channel invite. Optional field.
​
target_user
user object
The user whose stream to display for this voice channel stream invite. Optional field.
​
target_application
partial application object
The embedded application to open for this voice channel embedded application invite. Optional field.
​
approximate_presence_count
integer
Approximate count of online members. Returned from GET /invites/{code} when with_counts is true. Optional field.
​
approximate_member_count
integer
Approximate count of total members. Returned from GET /invites/{code} when with_counts is true. Optional field.
​
expires_at
?ISO8601 timestamp
required
The expiration date of this invite. null if the invite does not expire.
​
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. Optional field.
​
flags
integer
Guild invite flags for guild invites. Optional field.
​
roles
array of partial role objects
The roles assigned to the user upon accepting the invite. Optional field. This is a partial role object containing only id, name, position, color, colors, icon, and unicode_emoji.

​
Invite types

TypeValue
GUILD0
GROUP_DM1
FRIEND2

​
Invite target types

TypeValue
STREAM1
EMBEDDED_APPLICATION2

​
Guild invite flags

FlagValueDescription
IS_GUEST_INVITE1 << 0This invite is a guest invite for a voice channel

​
Invite example

{
  "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. Extends the invite object.

​
Invite metadata structure

​
uses
integer
required
Number of times this invite has been used.
​
max_uses
integer
required
Max number of times this invite can be used.
​
max_age
integer
required
Duration in seconds after which the invite expires.
​
temporary
boolean
required
Whether this invite only grants temporary membership.
​
created_at
ISO8601 timestamp
required
When this invite was created.

​
Invite metadata example

{
  "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 object is deprecated.

​
Invite stage instance structure

​
members
array of partial guild member objects
required
The members speaking in the stage.
​
participant_count
integer
required
The number of users in the stage.
​
speaker_count
integer
required
The number of users speaking in the stage.
​
topic
string
required
The topic of the stage instance (1–120 characters).

​
Get invite

GET /invites/{invite.code}
Returns an invite object for the given code.

​
Query string params

​
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 /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.
This endpoint supports the X-Audit-Log-Reason header.

​
Get target users

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

​
Update target users

PUT /invites/{invite.code}/target-users
Updates the users allowed to see and accept this invite. Uploading a file with invalid user IDs returns a 400 with the invalid IDs described. Requires the caller to be the inviter or have MANAGE_GUILD permission.

​
Form params

​
target_users_file
file
required
A CSV file with a single column of user IDs for all the users able to accept this invite.

​
Error response example

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

​
Get target users job status

GET /invites/{invite.code}/target-users/job-status
Processing target users from a CSV when creating or updating an invite is done asynchronously. This endpoint lets you check the status of that job. Requires the caller to be the inviter, or have MANAGE_GUILD permission, or have VIEW_AUDIT_LOG permission.

​
Status codes

CodeNameDescription
0UNSPECIFIEDThe default value.
1PROCESSINGThe job is still being processed.
2COMPLETEDThe job has been completed successfully.
3FAILEDThe job has failed. See error_message for details.

​
Response example

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