Interest onboarding
The interest picker shows an account cards grouped by interest, such as games or public servers, and joins the account to the guilds behind the cards it picks. Staff curate the regions and options through the Admin interest onboarding API. A region is chosen for the request: the region asked for, else the one listing the IP country, else the one listing the app language, else the default region.
An account must finish the picker once when it is on and at least one enabled region has an enabled option. That covers an account created since the picker was first turned on, for 30 days after it was created, and an account created before it that the existing accounts rollout share reaches, until it finishes. Bot and system accounts never get it. While an account must finish it, the Ready payload carries interest_onboarding_required as true; the field is absent otherwise. There is no way to skip the picker.
Interest onboarding option object
Section titled “Interest onboarding option object”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the option |
| name | string | The card title |
| group | ?string | The heading the card is listed under, null for none |
| asset1 | ?string | The logo hash, null for none |
1 The media proxy serves the logo at /branding/cosmetic-interest-{id}/{asset}.webp on the instance’s media endpoint
Interest onboarding region summary object
Section titled “Interest onboarding region summary object”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the region |
| name | string | The region label |
Interest onboarding object
Section titled “Interest onboarding object”| Field | Type | Description |
|---|---|---|
| region_id | ?snowflake | The region shown, null when the picker has nothing to show |
| regions | array[interest onboarding region summary object] | Enabled regions with at least one enabled option, for the region switcher |
| options | array[interest onboarding option object] | Enabled options of the shown region in admin order, each group together where its first option stands |
Interest onboarding join result object
Section titled “Interest onboarding join result object”| Field | Type | Description |
|---|---|---|
| option_id | ?snowflake | The chosen option, null for the official guild |
| guild_id | snowflake | The guild |
| status | string | joined, already_member or failed |
A failed join means a ban, a full guild, the guild limit, closed invites, the guild cap of the picker or an error kept the account out.
Complete interest onboarding response object
Section titled “Complete interest onboarding response object”| Field | Type | Description |
|---|---|---|
| already_completed | boolean | True when the account had already finished; nothing was joined |
| results1 | array[interest onboarding join result object] | The official guild first, then one entry per guild in request order |
1 A guild of several chosen options appears once, under the first
Get interest onboarding
Section titled “Get interest onboarding”GET/v1/users/@me/interest-onboardingReturns the interest onboarding object for the region the request resolves to. The list is public, so it is returned whether or not the caller must finish the picker. It is empty while the picker is off.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| region_id? | snowflake | Show this region instead of the one the request resolves to |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding object | The picker was returned |
| 401 | error response | No account is signed in |
| 403 | error response | The credential is a bot or OAuth2 bearer token, returned as ACCESS_DENIED |
Rate limit
Section titled “Rate limit”30 requests per minute for each authenticated user, on the interest_onboarding:get bucket.
Complete interest onboarding
Section titled “Complete interest onboarding”POST/v1/users/@me/interest-onboardingJoins the account to the official guild, when one is set, and to the guilds of every chosen option, then marks the picker finished. Returns the complete interest onboarding response object. An account finishes the picker once; a later call returns already_completed as true.
The account joins as itself, so bans, guild limits and the username gate apply. A failed join never stops the others. The chosen options join at most 20 distinct guilds; any past that are returned as failed. When every join failed for a passing fault, such as a server error or a rate limit, the picker is not marked finished and the account sees it again.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The region the options come from |
| option_ids1 | array[snowflake] | 2-10 enabled options of the region, without repeats |
1 A region with fewer than 2 enabled options takes all of them
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | complete interest onboarding response object | The picker was finished, or had been already |
| 400 | error response | An option is not an enabled option of an enabled region, or too few options were chosen, returned as INVALID_FORM_BODY |
| 401 | error response | No account is signed in |
| 403 | error response | The picker is off, returned as FEATURE_TEMPORARILY_DISABLED |
| 403 | error response | The account is not one that must finish the picker, returned as FORBIDDEN |
| 403 | error response | The credential is a bot or OAuth2 bearer token, returned as ACCESS_DENIED |
Rate limit
Section titled “Rate limit”5 requests per minute for each authenticated user, on the interest_onboarding:complete bucket.