Quickstart

Simple endpoints for single lookups, batch jobs, and account-backed API access.

GetGender.io exposes signup, session auth, API-key protected lookup routes, CSV uploads, and billing on a single API surface. The docs stay focused on what engineers actually need to ship.

Access

Account signup and login

Create a free account with POST /api/v1/auth/signup. The response includes a one-time live API key and a reusable session token for dashboard actions.

Signup

POST /api/v1/auth/signup
{
  "email": "anna@getgender.io",
  "password": "supersecret",
  "fullName": "Anna Schmidt",
  "companyName": "Acme"
}

Login uses POST /api/v1/auth/login. Protected account routes accept Authorization: Bearer gg_session_... or X-Session-Token.

Security

Lookup authentication

Lookup endpoints under /api/v1/gender* and /api/v1/csv/upload require an API key. The recommended production header is X-API-Key.

Headers

X-API-Key: gg_live_your_api_key
Authorization: Bearer gg_session_your_dashboard_token

Quickstart

Quickstart request

JavaScript

fetch('/api/v1/gender?name=Anna&country=DE', {
  headers: {
    'X-API-Key': 'gg_live_your_api_key'
  }
})
// { gender: "female", confidence: 0.98 }

cURL

curl "https://getgender.io/api/v1/gender?name=Anna&country=DE" \
  -H "X-API-Key: gg_live_your_api_key"

Surface area

Endpoints

POST /api/v1/auth/signup

Create an account, issue a primary API key, and return a session token.

POST /api/v1/auth/login

Exchange email and password for a dashboard session token.

GET /api/v1/account/dashboard

Return live usage, API keys, recent lookups, recent CSV jobs, and subscription state.

GET /api/v1/gender?name=Anna&country=DE

Resolve gender from a first name with an optional ISO country signal.

GET /api/v1/gender/full?name=Anna+Schmidt&country=DE

Parse the first token from a full name while preserving the same response shape.

GET /api/v1/gender/email?email=anna.schmidt@gmail.com

Infer gender from the email username portion when names are embedded in the local part.

POST /api/v1/gender/batch

Send an array of up to 100 names for synchronous bulk classification.

POST /api/v1/csv/upload

Upload CSV files and persist row-level results for dashboard visibility.

POST /api/v1/billing/checkout

Start Stripe Checkout for Starter, Growth, or Scale using an account or submitted email.

Payloads

Response shape

Every lookup returns the resolved gender together with a confidence score, normalized name, and source so applications can apply their own thresholds.

JSON

{
  "input": "Anna",
  "normalizedName": "anna",
  "countryCode": "DE",
  "gender": "female",
  "confidence": 0.98,
  "source": "database",
  "mode": "first_name"
}