Gender From Username API – Single Request Documentation

Request overview

From username to likely name

GenderAPI looks for name signals inside the submitted handle, then predicts gender using database evidence, country context and—when requested—AI fallback.

Inputsparkling_unicorn

Extracted signalSparkling

Predictionfemale · 92%

MethodPOST

Content typeapplication/json

AuthenticationBearer token

AI optionsAvailable

HDR

Required HTTP headers

Authorize the request

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

JSON request body

Parameters

Parameter	Type	Requirement	Description
`username`	string	Required	Username, social handle, display name or nickname to analyze.
`country`	string	Optional	ISO 3166-1 alpha-2 country code, such as US or TR, for regional context.
`askToAI`	boolean	Optional	When true, use AI fallback if the extracted name has no database result.
`forceToGenderize`	boolean	Optional	When true, attempt a prediction for aliases or inputs that do not resemble typical names.

askToAI

Use only when the extracted name has no database result.

forceToGenderize

Allows attempts for fantasy terms, brand-like aliases and unusual nicknames.

Confidence matters: Forced results for weak or non-human name signals can be less reliable. Evaluateprobability before acting on a prediction.

Code examples

Send a username request

cURL

curl -X POST "https://api.genderapi.io/api/username" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"username":"sparkling_unicorn","country":"US","askToAI":true,"forceToGenderize":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/username", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ username: "sparkling_unicorn", country: "US", askToAI: true, forceToGenderize: true })
});

Python

import requests
response = requests.post(
  "https://api.genderapi.io/api/username",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"username": "sparkling_unicorn", "country": "US", "askToAI": True, "forceToGenderize": True}
)
print(response.json())

200 response

Extracted signal and prediction

JSON

{
  "status": true, "used_credits": 1, "remaining_credits": 4999,
  "expires": 1743659200, "q": "sparkling_unicorn",
  "name": "Sparkling", "gender": "female", "country": "US",
  "total_names": 9876, "probability": 92, "duration": "6ms"
}

Response fields

Field	Type	Description
`status`	boolean	Whether the request completed successfully.
`used_credits`	integer	Credits consumed by this request.
`remaining_credits`	integer	Credits available after the request.
`expires`	integer	Package expiration time as a UNIX timestamp.
`q`	string	Original username submitted in the request.
`name`	string	Likely name extracted from the username.
`gender`	string \| null	Predicted value: male, female or null.
`country`	string	Country code considered for the prediction.
`total_names`	integer	Number of samples supporting the prediction.
`probability`	integer	Prediction confidence as a percentage.
`duration`	string	Server processing time.

Treat usernames as indirect signals

A username may describe a brand, character or concept rather than a person. Confirm an extracted name is meaningful and establish an acceptable probability threshold for your use case.

Next guide

Analyze multiple usernames

Username multiple requestProcess several handles in one request →Email single requestExtract a name from an email →