Skip to main content
GET
/
check
Check username
curl --request GET \
  --url https://api.username.dev/check \
  --header 'Authorization: Bearer <token>'
{
  "username": "berlin",
  "isReserved": true,
  "isDeleted": false,
  "categories": [
    {
      "category": "city",
      "metadata": {
        "country": "DE"
      }
    },
    {
      "category": "government",
      "metadata": {
        "country": "DE"
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key in format: un_live_<32-char-random>. Get your API key from the dashboard at https://app.username.dev/dashboard

Query Parameters

​
input
string
required

The username to check. Can contain any characters including Unicode. Whitespace will be removed, and the input will be converted to lowercase during normalization.

Minimum string length: 1

Response

Successful response. Returns username validation results. Note: Both reserved and non-reserved usernames return 200 status. Check the isReserved field to determine if the username is available.

Response containing username validation results, reservation status, deletion status, and associated categories with metadata.

​
username
string
required

The normalized username that was checked (whitespace removed, lowercase).

Example:

"berlin"

​
isReserved
boolean
required

Whether the username is reserved (exists in the database with one or more categories). True if reserved, false if available.

Example:

true

​
isDeleted
boolean
required

Whether the username has been marked as deleted. Deleted usernames are still considered reserved but may be flagged differently in your application.

Example:

false

​
categories
object[]
required

List of categories associated with this username. Empty array if username is not reserved. Categories can include: other, dictionary, city, country, region, brand, first_name, last_name, system, restricted, product, celebrity, government, agency, institution, event, company, place, organization.

Example:
[
  {
    "category": "city",
    "metadata": { "country": "DE" }
  },
  {
    "category": "government",
    "metadata": { "country": "DE" }
  }
]