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

---