Users v1

Reference for the Users v1 endpoints on Roblox.

Base URL: https://users.roblox.com

Endpoints

Method	Path	Name
`GET`	`/v1/birthdate`	`getBirthdate`
`POST`	`/v1/birthdate`	`postBirthdate`
`GET`	`/v1/description`	`getDescription`
`POST`	`/v1/description`	`postDescription`
`GET`	`/v1/display-names/validate`	`getDisplayNamesValidate`
`GET`	`/v1/gender`	`getGender`
`POST`	`/v1/gender`	`postGender`
`POST`	`/v1/usernames/users`	`postUsernamesUsers`
`POST`	`/v1/users`	`postUsers`
`GET`	`/v1/users/:userId`	`getUsersUserid`
`PATCH`	`/v1/users/:userId/display-names`	`patchUsersUseridDisplayNames`
`GET`	`/v1/users/:userId/display-names/validate`	`getUsersUseridDisplayNamesValidate`
`GET`	`/v1/users/:userId/username-history`	`getUsersUseridUsernameHistory`
`GET`	`/v1/users/authenticated`	`getUsersAuthenticated`
`GET`	`/v1/users/authenticated/age-bracket`	`getUsersAuthenticatedAgeBracket`
`GET`	`/v1/users/authenticated/country-code`	`getUsersAuthenticatedCountryCode`
`GET`	`/v1/users/authenticated/roles`	`getUsersAuthenticatedRoles`
`GET`	`/v1/users/search`	`getUsersSearch`

`getBirthdate`

GET /v1/birthdate

Get the user’s birthdate

Usage

import { fetchApi } from 'rozod';
import { getBirthdate } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getBirthdate, undefined);

Response

Field	Type	Description
`birthMonth`	`number`
`birthDay`	`number`
`birthYear`	`number`

Errors

Status	Description
400	1: User not found.
401	0: Authorization has been denied for this request.

`postBirthdate`

POST /v1/birthdate

Update the user’s birthdate

Usage

import { fetchApi } from 'rozod';
import { postBirthdate } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(postBirthdate, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`birthMonth`	`number`
`birthDay`	`number`
`birthYear`	`number`
`password`	`string`

Response

Type: unknown

Errors

Status	Description
400	1: User not found. 4: The birthdate provided is invalid. 8: Password is incorrect.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: PIN is locked. 5: Invalid birthdate change.
500	0: An unknown error occured. 5: Invalid birthdate change.

`getDescription`

GET /v1/description

Get the user’s description

Usage

import { fetchApi } from 'rozod';
import { getDescription } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getDescription, undefined);

Response

Field	Type	Description
`description`	`string`

Errors

Status	Description
400	1: User not found.
401	0: Authorization has been denied for this request.

`postDescription`

POST /v1/description

Update the user’s description

Usage

import { fetchApi } from 'rozod';
import { postDescription } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(postDescription, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`description`	`string`

Response

Field	Type	Description
`description`	`string`

Errors

Status	Description
400	1: User not found.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: PIN is locked.
500	0: An unknown error occured.
503	3: This feature is currently disabled. Please try again later.

`getDisplayNamesValidate`

GET /v1/display-names/validate

Validate a display name for a new user.

Usage

import { fetchApi } from 'rozod';
import { getDisplayNamesValidate } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getDisplayNamesValidate, {
  displayName: /* string */,
  birthdate: /* string */
});

Parameters

Name	Type	Required	Description
`displayName`	`string`	Yes	The display name.
`birthdate`	`string`	Yes	The new user’s birthdate

Response

Type: unknown

Errors

Status	Description
400	1: Display name is too short 2: Display name is too long 3: Display name contains invalid characters 4: Display name has been moderated 6: Request must contain a birthdate 8: Display name has too many combinations of character sets
429	5: Display name updates for this user have been throttled

`getGender`

GET /v1/gender

Get the user’s gender

Usage

import { fetchApi } from 'rozod';
import { getGender } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getGender, undefined);

Response

Field	Type	Description
`gender`	`number`

Errors

Status	Description
400	1: User not found.
401	0: Authorization has been denied for this request.

`postGender`

POST /v1/gender

Update the user’s gender

Usage

import { fetchApi } from 'rozod';
import { postGender } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(postGender, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`gender`	`“Unknown"	"Male"

Response

Type: unknown

Errors

Status	Description
400	1: User not found. 6: The gender provided is invalid.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: PIN is locked.
500	0: An unknown error occured.

`postUsernamesUsers`

POST /v1/usernames/users

Get users by usernames.

Usage

import { fetchApi } from 'rozod';
import { postUsernamesUsers } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(postUsernamesUsers, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`usernames`	`string[]`
`excludeBannedUsers`	`boolean`

Response

Field	Type	Description
`data`	`object[]`	See below

data[] item fields:

Field	Type	Description
`requestedUsername`	`string`
`hasVerifiedBadge`	`boolean`
`id`	`number`
`name`	`string`
`displayName`	`string`

Errors

Status	Description
400	2: Too many usernames.

`postUsers`

POST /v1/users

Get users by ids.

Usage

import { fetchApi } from 'rozod';
import { postUsers } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(postUsers, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`userIds`	`number[]`
`excludeBannedUsers`	`boolean`

Response

Field	Type	Description
`data`	`object[]`	See below

data[] item fields:

Field	Type	Description
`hasVerifiedBadge`	`boolean`
`id`	`number`
`name`	`string`
`displayName`	`string`

Errors

Status	Description
400	1: Too many ids.

`getUsersUserid`

GET /v1/users/:userId

Gets detailed user information by id.

Usage

import { fetchApi } from 'rozod';
import { getUsersUserid } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersUserid, {
  userId: /* integer */
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes	The user id.

Response

Field	Type	Description
`description`	`string`
`created`	`string`
`isBanned`	`boolean`
`externalAppDisplayName`	`string`
`hasVerifiedBadge`	`boolean`
`id`	`number`
`name`	`string`
`displayName`	`string`

Errors

Status	Description
404	3: The user id is invalid.

`patchUsersUseridDisplayNames`

PATCH /v1/users/:userId/display-names

Set the display name for the authorized user.

Usage

import { fetchApi } from 'rozod';
import { patchUsersUseridDisplayNames } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(patchUsersUseridDisplayNames, {
  userId: /* integer */,
  body: { /* ... */ }
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes	the user id

Request Body

Field	Type	Description
`newDisplayName`	`string`

Response

Type: unknown

Errors

Status	Description
400	1: Display name is too short 2: Display name is too long 3: Display name contains invalid characters 4: Display name has been moderated 8: Display name has too many combinations of character sets
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 7: The user id is invalid.
429	5: Display name updates for this user have been throttled

`getUsersUseridDisplayNamesValidate`

GET /v1/users/:userId/display-names/validate

Validate a display name for an existing user.

Usage

import { fetchApi } from 'rozod';
import { getUsersUseridDisplayNamesValidate } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersUseridDisplayNamesValidate, {
  userId: /* integer */,
  displayName: /* string */
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes	The user id.
`displayName`	`string`	Yes	The display name.

Response

Type: unknown

Errors

Status	Description
400	1: Display name is too short 2: Display name is too long 3: Display name contains invalid characters 4: Display name has been moderated 8: Display name has too many combinations of character sets
401	0: Authorization has been denied for this request.
403	7: The user id is invalid.
429	5: Display name updates for this user have been throttled

`getUsersUseridUsernameHistory`

GET /v1/users/:userId/username-history

Retrieves the username history for a particular user.

Usage

import { fetchApi } from 'rozod';
import { getUsersUseridUsernameHistory } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersUseridUsernameHistory, {
  userId: /* integer */,
  cursor: /* string? */,
  sortOrder: /* enum */
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes
`cursor`	`string?`	No	The paging cursor for the previous or next page.
`sortOrder`	`enum`	Yes	The order the results are sorted in.

Response

Field	Type	Description
`previousPageCursor`	`string`
`nextPageCursor`	`string`
`data`	`object[]`	See below

data[] item fields:

Field	Type	Description
`name`	`string`

Errors

Status	Description
400	3: The user id is invalid.

`getUsersAuthenticated`

GET /v1/users/authenticated

Gets the minimal authenticated user.

Usage

import { fetchApi } from 'rozod';
import { getUsersAuthenticated } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersAuthenticated, undefined);

Response

Field	Type	Description
`id`	`number`
`name`	`string`
`displayName`	`string`

Errors

Status	Description
401	0: Authorization has been denied for this request.

`getUsersAuthenticatedAgeBracket`

GET /v1/users/authenticated/age-bracket

Gets the age bracket of the authenticated user.

Usage

import { fetchApi } from 'rozod';
import { getUsersAuthenticatedAgeBracket } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersAuthenticatedAgeBracket, undefined);

Response

Field	Type	Description
`ageBracket`	`number`

Errors

Status	Description
401	0: Authorization has been denied for this request.

`getUsersAuthenticatedCountryCode`

GET /v1/users/authenticated/country-code

Gets the country code of the authenticated user.

Usage

import { fetchApi } from 'rozod';
import { getUsersAuthenticatedCountryCode } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersAuthenticatedCountryCode, undefined);

Response

Field	Type	Description
`countryCode`	`string`

Errors

Status	Description
401	0: Authorization has been denied for this request.

`getUsersAuthenticatedRoles`

GET /v1/users/authenticated/roles

Gets the (public) roles of the authenticated user, such as "Soothsayer" and "BetaTester".

Usage

import { fetchApi } from 'rozod';
import { getUsersAuthenticatedRoles } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersAuthenticatedRoles, undefined);

Response

Field	Type	Description
`roles`	`string[]`

Errors

Status	Description
401	0: Authorization has been denied for this request.

`getUsersSearch`

GET /v1/users/search

Searches for users by keyword.

Usage

import { fetchApi } from 'rozod';
import { getUsersSearch } from 'rozod/lib/endpoints/usersv1';

const data = await fetchApi(getUsersSearch, {
  keyword: /* string */,
  sessionId: /* string? */,
  cursor: /* string? */
});

Parameters

Name	Type	Required	Description
`keyword`	`string`	Yes	The search keyword.
`sessionId`	`string?`	No
`cursor`	`string?`	No	The paging cursor for the previous or next page.

Response

Field	Type	Description
`previousPageCursor`	`string`
`nextPageCursor`	`string`
`data`	`object[]`	See below

data[] item fields:

Field	Type	Description
`previousUsernames`	`string[]`
`hasVerifiedBadge`	`boolean`
`id`	`number`
`name`	`string`
`displayName`	`string`

Errors

Status	Description
400	5: The keyword was filtered. 6: The keyword is too short.
429	4: Too many requests.