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

GET/invites/{invite.code}

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/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 from the original file passed to invite create 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 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"
  ]
}

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