Guild Join Request Resource

Guilds that have Server Member Applications set up with manual approval require prospective members to submit a join request. A join request contains the applicant’s answers to the guild’s member verification form, and stays pending until a moderator approves or rejects it. While a join request is pending, the applicant may already have a guild member object with pending set to true, depending on whether the guild has PREVIEW_ENABLED. When a request is approved, the member’s pending field becomes false and a Guild Member Update Gateway event is fired.

The endpoints on this page are only available for guilds with both the MEMBER_VERIFICATION_GATE_ENABLED and MEMBER_VERIFICATION_MANUAL_APPROVAL features. Other guilds receive a 403 Forbidden response.

Apps can also follow join requests in real time using the Guild Join Request Create, Guild Join Request Update, and Guild Join Request Delete Gateway events, which require the GUILD_MODERATION intent and the KICK_MEMBERS permission.

Guild Join Request Object

Guild Join Request Structure

Field	Type	Description
id	snowflake	ID of the join request
created_at	ISO8601 timestamp	when the applicant started the join request
reviewed_at	?ISO8601 timestamp	when the join request was approved or rejected
application_status	?string	status of the join request
rejection_reason	?string	reason the join request was rejected, only set when `application_status` is `REJECTED`
guild_id	snowflake	ID of the guild the applicant is applying to
user_id	snowflake	ID of the applicant
user?	?user object	the applicant
form_responses?	?array of form field response objects	applicant’s responses to the guild’s member verification form
actioned_by_user?	?user object	user who approved or rejected the join request

Application Status

Value	Description
STARTED	applicant started but has not yet submitted their join request
SUBMITTED	applicant submitted their join request, which is awaiting review
APPROVED	join request was approved
REJECTED	join request was rejected

Example Guild Join Request

{
  "id": "1345216948159746048",
  "created_at": "2025-02-28T21:47:23.681000+00:00",
  "reviewed_at": null,
  "application_status": "SUBMITTED",
  "rejection_reason": null,
  "guild_id": "613425648685547541",
  "user_id": "53908232506183680",
  "user": {
    "id": "53908232506183680",
    "username": "nelly",
    "discriminator": "0",
    "global_name": "Nelly",
    "avatar": "8342729096ea3675442027381ff50dfe",
    "public_flags": 131328,
    "flags": 131328,
    "primary_guild": null
  },
  "form_responses": [
    {
      "field_type": "TERMS",
      "label": "Server Rules",
      "required": true,
      "values": [
        "Be respectful",
        "No spam"
      ],
      "response": true
    },
    {
      "field_type": "TEXT_INPUT",
      "label": "How did you find this server?",
      "required": true,
      "response": "A friend invited me"
    }
  ]
}

Form Field Response Object

Each entry in a join request’s form_responses array represents one field on the guild’s member verification form, along with the applicant’s answer to it. The fields present on an entry depend on its field_type.

Form Field Response Structure

These fields are present on every form field response.

Field	Type	Description
field_type	string	type of form field
label?	string	label shown above the field
description?	string	helper text shown below the label
required?	boolean	whether the applicant must fill in the field

Form Field Type

Value	Description
TERMS	field requiring the applicant to acknowledge a list of terms
TEXT_INPUT	short text input field
PARAGRAPH	long-form text input field
MULTIPLE_CHOICE	field where the applicant selects one of many options

Terms Form Field Response Extra Fields

Field	Type	Description
values	array of strings	terms the applicant must acknowledge
response?	boolean	whether the applicant accepted the terms

Text Input and Paragraph Form Field Response Extra Fields

Field	Type	Description
placeholder?	string	placeholder text shown in empty input
response?	string	applicant’s text response

Multiple Choice Form Field Response Extra Fields

Field	Type	Description
choices	array of strings	choices the applicant can select from
response?	integer	index of the choice selected by the applicant

Example Form Field Responses

[
  {
    "field_type": "TERMS",
    "label": "Server Rules",
    "description": "You must agree to all of the rules to join",
    "required": true,
    "values": [
      "Be respectful",
      "No spam"
    ],
    "response": true
  },
  {
    "field_type": "PARAGRAPH",
    "label": "Why do you want to join?",
    "required": true,
    "placeholder": "Tell us a bit about yourself",
    "response": "I'm looking for people to play with on the weekends."
  },
  {
    "field_type": "MULTIPLE_CHOICE",
    "label": "Which platform do you play on?",
    "required": true,
    "choices": [
      "PC",
      "PlayStation",
      "Xbox"
    ],
    "response": 0
  }
]

List Guild Join Requests

Returns a list of guild join request objects for the guild. Requires the KICK_MEMBERS or MANAGE_GUILD permission.

The guild_join_requests array is only returned to apps with the KICK_MEMBERS permission. Apps that only have MANAGE_GUILD receive the count of pending join requests without the requests themselves.

Results are always filtered to a single application status. Omitting status returns the default SUBMITTED join requests.

Query String Params

Field	Type	Description	Default
status?	string	application status to filter by; one of `SUBMITTED`, `APPROVED`, or `REJECTED`	SUBMITTED
limit?	integer	max number of join requests to return (1-100)	100
before? *	snowflake	get join requests before this value	null
after? *	snowflake	get join requests after this value	null

* Provide a snowflake to before or after for pagination. For SUBMITTED join requests, the value is compared against the request’s id, and requests are returned in descending order by id. For APPROVED and REJECTED join requests, the value is compared against when the request was reviewed. If both before and after are provided, only after is respected.

Response Structure

Field	Type	Description
total?	integer	number of join requests with the given status, only returned when `status` is `SUBMITTED` or omitted
guild_join_requests?	array of guild join request objects	the join requests, only returned with the `KICK_MEMBERS` permission

Example Response

{
  "total": 2,
  "guild_join_requests": [
    {
      "id": "1345216948159746048",
      "created_at": "2025-02-28T21:47:23.681000+00:00",
      "reviewed_at": null,
      "application_status": "SUBMITTED",
      "rejection_reason": null,
      "guild_id": "613425648685547541",
      "user_id": "53908232506183680",
      "user": {
        "id": "53908232506183680",
        "username": "nelly",
        "discriminator": "0",
        "global_name": "Nelly",
        "avatar": "8342729096ea3675442027381ff50dfe",
        "public_flags": 131328,
        "flags": 131328,
        "primary_guild": null
      },
      "form_responses": [
        {
          "field_type": "TEXT_INPUT",
          "label": "How did you find this server?",
          "required": true,
          "response": "A friend invited me"
        }
      ]
    }
  ]
}

Action Guild Join Request

Approve or reject a join request. Requires the KICK_MEMBERS permission. Returns the updated guild join request object on success. Fires a Guild Join Request Update Gateway event, and a Guild Member Update Gateway event when the request is approved. Only join requests with an application_status of SUBMITTED can be actioned. Requests that have already been approved or rejected are returned unchanged, and requests in any other status return a 404 Not Found response.

JSON Params

Field	Type	Description
action	string	either `APPROVED` or `REJECTED`
rejection_reason?	?string	reason for rejection (max 160 characters), only used when `action` is `REJECTED`

API Reference

SDK Reference

HTTP API Resources

Events

Voice & RPC

Guild Join Request Object

Guild Join Request Structure

Application Status

Example Guild Join Request

Form Field Response Object

Form Field Response Structure

Form Field Type

Terms Form Field Response Extra Fields

Text Input and Paragraph Form Field Response Extra Fields

Multiple Choice Form Field Response Extra Fields

Example Form Field Responses

List Guild Join Requests

Query String Params

Response Structure

Example Response

Action Guild Join Request

JSON Params

​Guild Join Request Object

Guild Join Request Structure

Application Status

Example Guild Join Request

​Form Field Response Object

Form Field Response Structure

Form Field Type

Terms Form Field Response Extra Fields

Text Input and Paragraph Form Field Response Extra Fields

Multiple Choice Form Field Response Extra Fields

Example Form Field Responses

​List Guild Join Requests

Query String Params

Response Structure

Example Response

​Action Guild Join Request

JSON Params

Guild Join Request Object

Form Field Response Object

List Guild Join Requests

Action Guild Join Request