Invites

An invite is a code that admits an account into a guild or a group direct message.

Get invite is the only route here that needs no credential. Modify guild custom invite URL configures a guild’s custom invite URL, and Discovery defines joining an approved public guild with no invite.

Invite object

An invite object describes one code and the target it admits into. The type selects the representation.

Structure

Field	Type	Description
code	string	The unique code that identifies the invite
type	integer	Invite type
guild?1	partial guild object	The guild the invite admits into
channel?2	partial invite channel object	The guild channel or group direct message the invite targets
inviter3	?partial user object	The account that created the invite, or null
member_count?4	integer	The member count of the guild, or the exact recipient count of the group direct message
presence_count?4	integer	The online member count of the guild
expires_at5	?ISO8601 timestamp	The time at which the invite stops resolving, or null when it never expires
temporary6	boolean	Whether admission through this invite grants temporary membership

¹ Present only when type is 0, and it applies the same feature-gated asset stripping as the full guild object

² Present when type is 0 or 1. A guild invite with no stored target channel resolves the first guild text channel the default role can view

³ Null when the record stores no creator, which is always the case for a custom invite URL

⁴ Guild counts are 0 when unavailable

⁵ Computed from the creation time plus the stored lifetime, and null whenever that lifetime is 0

⁶ Has no effect on a group direct message invite

Branch on type to know which fields arrive

A guild invite always has guild, channel, member_count, and presence_count. A group direct message invite has channel and member_count only.

Example

{
  "code": "aB3dEf7h",
  "type": 0,
  "guild": {"id": "1489002177550843904", "name": "Example guild"},
  "channel": {"id": "1489002177550843905", "name": "general", "type": 0},
  "inviter": {"id": "1501314428688998182", "username": "example"},
  "member_count": 412,
  "presence_count": 87,
  "expires_at": null,
  "temporary": false
}

Invite types

Value	Name	Description
0	GUILD	An invite that admits an account into a guild
1	GROUP_DM	An invite that admits an account into a group direct message

Invite metadata object

The metadata object extends the invite with its creation and usage state. Create channel invite, List channel invites, and List guild invites return it. Get invite never does.

Structure

Field	Type	Description
created_at	ISO8601 timestamp	The time at which the invite record was created
uses1	integer	The number of admissions completed through the invite
max_uses2	integer	The maximum admissions the invite permits, where 0 is unlimited
max_age?3	integer	The stored lifetime in seconds, where 0 never expires

¹ The counter advances only when the admission adds the account, so accepting an invite for a target the account already belongs to leaves it unchanged

² The value is 0 for every custom invite URL and for any invite created without an explicit maximum

³ Present only when type is 0, because a group direct message invite reports its expiry only through expires_at

Example

{
  "code": "aB3dEf7h",
  "type": 0,
  "created_at": "2026-08-04T11:22:19.000Z",
  "uses": 3,
  "max_uses": 25,
  "max_age": 86400,
  "temporary": false
}

Partial invite channel object

The partial channel has only enough identity to describe the target before admission.

Structure

Field	Type	Description
id	snowflake	The ID of the channel
name1	?string	The name of the channel, or null
type	integer	Channel type
recipients?2	array[partial invite recipient object]	The accounts in the group direct message

¹ A guild channel always stores a name, and a group direct message that stores no name reports null

² Present only on a group direct message invite, and it lists every current recipient including the invite creator

Partial invite recipient object

A partial recipient has only the username.

Structure

Field	Type	Description
username	string	The username of the recipient

Example

{
  "username": "example"
}

Custom invite URLs

Modify guild custom invite URL creates or replaces a custom invite code. It has type 0, null inviter and expires_at, and max_uses and max_age of 0. Its channel is the first guild text channel in channel order that the default role can view.

Custom invite codes are case-insensitive. Clearing or replacing a code makes the old link stop resolving immediately.

Accept invite records the join as a custom invite URL admission and attributes no inviter and no source invite code. List channel invites and List guild invites exclude custom invite URLs, and Delete invite refuses them.

Get invite

GET/v1/invites/{invite_code}Unauthenticated

Reads one invite. Returns an invite object on success.

An Authorization header that cannot be resolved is ignored, and the route returns the same representation to every caller. The read consumes no use.

Codes from Create channel invite are case-sensitive. Custom invite codes are case-insensitive.

Every admission gate runs at accept time

A 200 response means the invite code exists and none of the 404 conditions in the response table below applies. Accept invite checks bans, the guild’s invites-disabled feature, exhausted uses, the active presence a temporary invite requires, and whether the target is full.

Lookup does not guarantee admission

Expired invites no longer resolve. An exhausted invite may still resolve until an acceptance attempt removes it.

Path parameters

Field	Type	Description
invite_code1	string	The invite code to resolve (1 through 256 characters)

¹ Normalised before lookup by removing form feed and right-to-left override characters and trimming, and a value empty or above 256 characters afterwards returns the field code STRING_LENGTH_INVALID

Response

Status	Body	Condition
200	invite object	Invite resolved
404	error response	No record has the code, a guild invite names no guild, a group direct message invite names no channel or unresolvable recipient, or a guild invite with no stored target channel exposes no viewable channel, each returning UNKNOWN_INVITE
404	error response	The stored target channel no longer exists and the request returns UNKNOWN_CHANNEL
404	error response	The named guild no longer exists and the request returns UNKNOWN_GUILD

Rate limit

100 requests per 10 seconds for each identity and invite code, on the invite:read::invite_code bucket. The identity is the authenticated account when a credential resolves, and otherwise the derived key for the client IP address.

Accept invite

POST/v1/invites/{invite_code}

Accepts an invite and admits the authenticated account into its target. Returns an invite object on success.

A guild admission emits Guild Create, Guild Member Add, User Settings Update, User Guild Settings Update, and Message Create Gateway events. A group direct message admission emits Channel Create, Channel Recipient Add, and Message Create Gateway events.

Limitations

• User-only, so a bot token is rejected with 403 ACCESS_DENIED.
• The caller needs no permission.

Exhausted invites stop working

Accepting an exhausted invite returns 404 UNKNOWN_INVITE and makes the code stop resolving. Custom invite URLs have no use limit.

Path parameters

Field	Type	Description
invite_code	string	The invite code to accept (1 through 256 characters)

Response

Status	Body	Condition
200	invite object	Account was admitted, or was already a member of the target
400	error response	A temporary guild invite is accepted without an active presence and the request returns TEMPORARY_INVITE_REQUIRES_PRESENCE
400	error response	An unclaimed account accepts a group direct message invite and the request returns UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS
400	error response	A type 1 invite names a private channel that is not a group direct message and the caller is not already a recipient and the request returns INVALID_CHANNEL_TYPE
400	error response	The caller already holds the maximum number of guilds and the request returns MAX_GUILDS
400	error response	The target is full and the request returns MAX_GUILD_MEMBERS or MAX_GROUP_DM_RECIPIENTS
403	error response	Caller is a bot or presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild has the invites-disabled feature and the request returns INVITES_DISABLED
403	error response	Instant invites are temporarily disabled for the guild and the request returns FEATURE_TEMPORARILY_DISABLED
403	error response	The caller is banned by account or email address and the request returns USER_BANNED_FROM_GUILD
403	error response	The caller is banned by network address and the request returns USER_IP_BANNED_FROM_GUILD
403	error response	A deferred phone verification requirement becomes due and the request returns ACCOUNT_SUSPICIOUS_ACTIVITY
404	error response	The named guild no longer exists and the request returns UNKNOWN_GUILD
404	error response	The target channel no longer exists and the request returns UNKNOWN_CHANNEL
404	error response	The code resolves to no record, the record is exhausted, a guild invite names no guild, or a group direct message invite names no channel or a channel that no longer exists, each returning UNKNOWN_INVITE

Side effects

When the account is already in the target, the route returns 200 with the invite object. It consumes no use and emits no Dispatch. A new admission consumes one use and removes the invite when its limit is reached. A failed admission consumes no use. If the invite’s channel has been deleted, the account can still join and consume a use even though the response is 404 UNKNOWN_CHANNEL.

A guild admission creates the membership, records whether the join used a custom invite URL or an instant invite, and adds the guild to the caller’s settings and folder layout. A temporary invite marks the membership temporary.

The joining account receives Guild Create. Guild Member Add is guild-wide and reaches every session connected to the guild, subject to the event filtering gates, which withhold it from a passive user session in a guild with more than 250 members. The joining account receives User Settings Update when the join changes its stored settings, and User Guild Settings Update when its default_hide_muted_channels setting is enabled. Unless the guild’s system_channel_flags has SUPPRESS_JOIN_NOTIFICATIONS or the guild has no system channel, the operation creates a join system message and delivers Message Create.

A group direct message admission adds the caller as a recipient and creates a recipient addition system message. The joining account receives Channel Create, the recipients the group already held receive Channel Recipient Add, and every recipient receives Message Create.

No admission path records a guild audit entry.

Rate limit

10 requests per 10 seconds for each authenticated user, on the invite:accept bucket, which is not partitioned by invite code.

Delete invite

DELETE/v1/invites/{invite_code}BotAudit reasonMFA

Deletes an invite permanently and returns 204 with an empty body. Emits an Invite Delete Gateway event.

Limitations

• A guild invite requires guild membership.
• The invite creator deletes it without holding MANAGE_GUILD, and any other member needs that permission.
• A group direct message invite requires the caller to be a current recipient and the owner of the group.

MANAGE_GUILD is an elevated permission, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level is elevated.

Non-membership and missing permission return the same 403

A non-member and a member without the permission both receive 403 MISSING_PERMISSIONS. A guild that no longer exists returns 404 UNKNOWN_GUILD.

Deletion is immediate and unrecoverable

The invite code can be allocated again later, and every outstanding link with that code stops resolving immediately.

Path parameters

Field	Type	Description
invite_code	string	The invite code to delete (1 through 256 characters)

Response

Status	Body	Condition
204	empty	Invite was deleted
400	error response	The caller is not the creator and the guild requires elevated multi-factor authentication that the caller lacks, and the request returns TWO_FACTOR_REQUIRED
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED, or the caller is not a guild member, is neither the creator nor a MANAGE_GUILD holder, or does not own the group direct message, each returning MISSING_PERMISSIONS
404	error response	The named guild no longer exists and the request returns UNKNOWN_GUILD
404	error response	No record has the code, the record is the guild’s current custom invite URL, or a guild invite names no target, each returning UNKNOWN_INVITE
404	error response	The group direct message no longer exists or the caller is not one of its recipients and the request returns UNKNOWN_CHANNEL

Side effects

A guild invite records an INVITE_DELETE audit action targeting the invite code, with the channel, creator, maximum uses, lifetime, and temporary flag as metadata, the removed record as the change set, and the supplied reason. FiveCord logs a failure to write that entry and still completes the request. The X-Audit-Log-Reason header is read but never recorded for a group direct message invite.

Sessions holding VIEW_AUDIT_LOG receive Guild Audit Log Entry Create. Invite Delete has only code, channel_id, and guild_id. The guild delivers it to the sessions holding MANAGE_CHANNELS on the channel named by channel_id, as event filtering states. A passive session in a guild with more than 250 members is suppressed after that filter. A group direct message invite creates no audit entry and delivers Invite Delete to every current recipient’s sessions, where no passive gate applies.

Rate limit

20 requests per 10 seconds for each authenticated user and invite code, on the invite:delete::invite_code bucket.

Create channel invite

POST/v1/channels/{channel_id}/invitesBotAudit reason

Creates an invite for a channel, or returns an existing equivalent invite. Returns an invite metadata object on success. Emits an Invite Create Gateway event when a new record is created.

Limitations

• A guild channel requires guild membership, VIEW_CHANNEL, and CREATE_INSTANT_INVITE in that exact channel.
• An age-restricted guild channel also requires an age-verified account.
• A private channel requires the caller to be a current recipient, and no ownership is required.

This operation does not require elevated multi-factor authentication.

Guild affiliation determines the invite type

A channel that belongs to a guild creates a guild invite. Any other channel the caller can resolve creates a type 1 invite, including a direct message and the personal notes channel. Of these type 1 invites, only one whose channel is a group direct message admits an account through Accept invite.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the guild channel or private channel

JSON body

Every field is optional and nullable, and an omitted or null value takes the stated default.

Field	Type	Description
max_uses?1	?integer	The maximum number of admissions (0-100, default 0, where 0 is unlimited)
max_age?1	?integer	The lifetime in seconds (0-604800, default 0, where 0 never expires)
unique?2	?boolean	Whether to create a new invite even when an equivalent one already exists (default false)
temporary?3	?boolean	Whether admission grants temporary membership (default false)

¹ A negative value, a max_uses above 100, or a max_age above 604,800 seconds is rejected with 400 INVALID_FORM_BODY on that field

² When false or omitted the operation returns an existing invite whose creator, target channel, maximum uses, lifetime, and temporary flag all match the request exactly. A custom invite URL never matches

³ Has no effect on a private channel invite

Response

Status	Body	Condition
200	invite metadata object	Invite was created, or an equivalent existing invite was returned
400	error response	The guild already holds its maximum number of invites and the request returns MAX_INVITES
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	Instant invites are temporarily disabled for the guild and the request returns FEATURE_TEMPORARILY_DISABLED
403	error response	The caller is not a guild member or lacks VIEW_CHANNEL or CREATE_INSTANT_INVITE and the request returns MISSING_PERMISSIONS
403	error response	The channel is age restricted and the account is not age verified and the request returns NSFW_CONTENT_AGE_RESTRICTED
404	error response	Channel does not exist, is pending deletion, or the caller is not a recipient of the private channel, each returning UNKNOWN_CHANNEL, or the channel’s guild no longer exists and the request returns UNKNOWN_GUILD

Side effects

Returning an existing equivalent invite changes nothing, records no audit entry, and emits no Dispatch.

Creating an invite allocates a random eight-character code drawn from the mixed-case alphanumeric alphabet. A guild invite records an INVITE_CREATE audit action targeting the invite code, with the channel, creator, maximum uses, lifetime, and temporary flag as metadata and the supplied reason, then delivers Guild Audit Log Entry Create to sessions holding VIEW_AUDIT_LOG. FiveCord logs a failure to write that entry and still completes the request. The X-Audit-Log-Reason header is read but never recorded for a private channel.

The guild delivers Invite Create to sessions holding MANAGE_CHANNELS on the invite’s channel, subject to event filtering. A private channel invite records no audit entry and delivers the event to every current recipient’s sessions.

The guild invite ceiling is its configured max_guild_invites limit, which defaults to 1,000. It includes invites across all channels and the custom invite URL.

Rate limit

20 requests per minute for each authenticated user and channel ID, on the invite:create::channel_id bucket.

List channel invites

GET/v1/channels/{channel_id}/invitesBotMFA

Returns the standard invites of one channel as an array of invite metadata objects, ordered by descending creation time.

Limitations

• A guild channel requires guild membership, VIEW_CHANNEL in that channel, and MANAGE_CHANNELS in the guild.
• An age-restricted guild channel also requires an age-verified account.
• A group direct message requires the caller to be a current recipient and its owner.

MANAGE_CHANNELS is an elevated permission, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level is elevated.

The operation is not paginated. Every matching record is returned in one response, bounded by the guild invite ceiling described by Create channel invite. The response excludes the custom invite URL record.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the guild channel or group direct message

Response

Status	Body	Condition
200	array[invite metadata object]	Invites were returned, and the array is empty when the channel holds none
400	error response	The guild requires elevated multi-factor authentication that the caller lacks and the request returns TWO_FACTOR_REQUIRED
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	The caller is not a guild member, lacks VIEW_CHANNEL or MANAGE_CHANNELS, or does not own the group direct message and the request returns MISSING_PERMISSIONS
403	error response	The channel is age restricted and the account is not age verified and the request returns NSFW_CONTENT_AGE_RESTRICTED
404	error response	Channel does not exist, is pending deletion, the caller is not a recipient of the private channel, or the private channel is not a group direct message, each returning UNKNOWN_CHANNEL, or the channel’s guild no longer exists and the request returns UNKNOWN_GUILD

Rate limit

40 requests per 10 seconds for each authenticated user and channel ID, on the invite:list::channel_id bucket.

List guild invites

GET/v1/guilds/{guild_id}/invitesBotMFA

Returns the standard invites of one guild across all of its channels as an array of invite metadata objects, ordered by descending creation time. Requires guild membership and MANAGE_GUILD.

MANAGE_GUILD is an elevated permission, so a caller who is neither the guild owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED in a guild whose MFA level is elevated.

The operation is not paginated. Every matching record is returned in one response, bounded by the guild invite ceiling described by Create channel invite. The response excludes the custom invite URL record, so a client reads the current custom invite code through Get guild custom invite URL.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	array[invite metadata object]	Invites were returned, and the array is empty when the guild holds none
400	error response	The guild requires elevated multi-factor authentication that the caller lacks and the request returns TWO_FACTOR_REQUIRED
403	error response	Caller presents a bearer credential and the request returns ACCESS_DENIED
403	error response	The guild is unavailable to the caller and the request returns MISSING_ACCESS
403	error response	The caller is not a member of the guild or lacks MANAGE_GUILD and the request returns MISSING_PERMISSIONS
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

Rate limit

40 requests per 10 seconds for each authenticated user and guild ID, on the invite:list::guild_id bucket.