# NameGender API: Gender from an email address These are implementation instructions for AI coding assistants such as Claude Code, Cursor and GitHub Copilot. They are generated from the OpenAPI 3.1 contract at https://namegender.com/openapi.json, so field names, limits and error codes match the live API. The human-readable reference is https://namegender.com/docs#email. ## Your task - Integrate `GET|POST https://namegender.com/api/v1/gender/email` into this codebase. - Use only the endpoints, parameters and response fields documented here. If the task needs something that is not documented, stop and ask instead of guessing. - Put the HTTP call in one small server-side function or class. Read the API key from an environment variable named `NAMEGENDER_API_KEY`. - Follow the language, HTTP client, logging and error-handling conventions already used in this codebase. If an official client library exists for this language (https://namegender.com/client-libraries), prefer it over hand-written HTTP code. - Apply every rule under "Implementation rules", then work through "Verify the integration". ## How the API behaves Every lookup endpoint accepts both GET and POST so it can be called from a browser, a shell or a server. All paths live under `/api/v1`; a future breaking change will get a new version prefix instead of altering these. **Success and failure.** The HTTP status code is the only success signal: a 200 carries the result, anything else carries the error body described below. There is no separate success flag in the JSON. **Credits.** One credit per resolved name, not per request: a bulk call for 100 names costs 100 credits. Credits are checked before any work starts, so a request is never half-processed. Free accounts get 100 credits per day. **Rate limit.** 1200 requests per minute per API key by default, counted per key rather than per IP so that several customers behind one address do not share a bucket. Every response carries `X-RateLimit-Remaining`; a 429 carries `Retry-After`. **Errors.** Every failure, at every status code, returns the same body shape. Branch on the machine-readable `error` field, never on `message`: messages are translated into 22 languages and their wording can change. **Support.** Each response carries a `request_id`, also sent as the `X-Request-Id` header. Quote it in any support request and we can find the exact call in our logs. You may send your own `X-Request-Id` to correlate with your tracing system. **Data version.** Responses include `data_version`, the name-dataset snapshot that produced the answer. If a result changes between two calls, comparing this field is the first thing to check. ## Authentication Every request needs an API key, sent in a request header. Accepted forms, in order of preference: - Recommended: `Authorization: Bearer `. - `X-Api-Key: `: Alternative header form, for clients that cannot set `Authorization`. Keys are never read from the query string or the request body. Keys start with `ng_live_`. Create one at https://namegender.com/register; every account gets 100 free credits per day. ## Endpoint - `GET https://namegender.com/api/v1/gender/email` with query-string parameters - `POST https://namegender.com/api/v1/gender/email` with a JSON body The local part is split on separators and digits, then resolved as a name. `john.doe@example.com` resolves as "John". ## Request Send the same fields either as query-string parameters (GET) or as a JSON body (POST with `Content-Type: application/json`). Prefer POST from server code: the input then stays out of access logs. | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | yes | The value to resolve. At most 200 characters. | | `country` | string | no | ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate. Exactly 2 characters. | | `ai_fallback` | boolean | no | Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: "llm"` so you can tell these apart. Requires AI lookups to be enabled in account settings; otherwise the call fails with `ai_consent_required`. Default `false`. | | `best_guess` | boolean | no | Applied to the first name extracted from the email: return its most likely gender even below the confidence threshold, instead of null. Check `probability` before trusting the result. Default `false`. | ## Example requests ```bash curl "https://namegender.com/api/v1/gender/email?email=john.doe%40example.com" \ -H "Authorization: Bearer $NAMEGENDER_API_KEY" curl "https://namegender.com/api/v1/gender/email?email=john.doe%40example.com&country=TR" \ -H "Authorization: Bearer $NAMEGENDER_API_KEY" curl -X POST "https://namegender.com/api/v1/gender/email" \ -H "Authorization: Bearer $NAMEGENDER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"john.doe@example.com","country":"TR"}' ``` ## Response HTTP 200. Resolved. `gender` is null when the name is not recognised — that is a successful answer of "we do not know", not an error, and it still costs one credit. | Field | Type | Description | | --- | --- | --- | | `credits_charged` | integer | How many credits this call took from the balance: one per value resolved. | | `credits_remaining` | integer | Balance once this call is paid for: purchased credits plus whatever is left of today's free quota. | | `data_version` | string \| null | Name-dataset snapshot that produced the answer. | | `request_id` | string \| null | Identifier of this call, also sent as the `X-Request-Id` header. Quote it in support requests. | | `query` | string | The input exactly as you sent it. | | `name` | string \| null | The first name actually looked up, after stripping titles and surnames. | | `first_name` | string \| null | Given name parsed from the input. Present even when `gender` is null, and not charged separately. Titles and initials are never returned. For Chinese, Korean and Japanese script the surname comes first in the input and is returned in `last_name`. | | `middle_name` | string \| null | Any further given names between the first name and the surname, for example "Fitzgerald" in "John Fitzgerald Kennedy". Initials are dropped. | | `last_name` | string \| null | Surname parsed from the input, including particles such as "van" or "de la". "Smith, John" is read as surname first. With a Spanish-speaking `country` the last two words are both surnames (Pérez García). Always null for usernames, where a surname cannot be told apart from any other word. | | `name_type` | string \| null | `organization` when the input carries a company marker (Acme LLC, Müller GmbH, Stanford University); `role` for shared mailboxes and placeholder accounts (info@, Customer Service, guest). Both return `gender: null` and no name parts. `personal` means no such marker was found; it does not confirm the input is a real name. null when the input is not a name at all. One of `personal`, `organization`, `role`, `null`. | | `gender` | string \| null | null means the dataset has no confident answer. This is not an error. One of `male`, `female`, `null`. | | `probability` | integer | Share of people with this name who have the reported gender. 0 when unknown. Measured against held-out data, answers at 80+ come true about 95% of the time, so this number runs slightly conservative rather than optimistic. Range 0–100. | | `sample_size` | integer | How many real people the answer is based on. A probability of 100 from a sample of 3 is weaker than 85 from a sample of 90,000 — read the two fields together. 0 means the source recorded proportions rather than counts. | | `country` | string \| null | The country the answer came from, when narrowed. | | `took_ms` | integer | Whole milliseconds spent resolving this value on our side; network time is not included. | | `source` | string | How the answer was reached. `db` exact match; `script` matched after transliterating a non-Latin script; `fuzzy` closest spelling; `llm` language model; `none` no answer. Use it to decide how much to trust a row. One of `db`, `script`, `fuzzy`, `llm`, `cache`, `none`. | | `confidence` | string | Sample size bucket: high ≥100 people, medium ≥25, low ≥1, unverified when the source gave proportions instead of counts. One of `high`, `medium`, `low`, `unverified`, `unknown`. | | `matched_as` | string \| null | For `fuzzy` and `script` sources, the dictionary entry that was actually matched. Always inspect this before accepting a fuzzy result. | Example: Recognised name: ```json { "credits_charged": 1, "credits_remaining": 4821, "data_version": "2026.08", "request_id": "req_9c1f5b2a7e0d4a13", "query": "Ayşe Yılmaz", "name": "Ayşe", "first_name": "Ayşe", "middle_name": null, "last_name": "Yılmaz", "name_type": "personal", "gender": "female", "country": null, "sample_size": 655, "probability": 99, "took_ms": 1, "source": "db", "confidence": "high", "matched_as": null } ``` Example: Name not in the dataset — a successful "we do not know": ```json { "credits_charged": 1, "credits_remaining": 4820, "data_version": "2026.08", "request_id": "req_1d7e3c9048ba52f6", "query": "Qzzxvv", "name": "Qzzxvv", "first_name": "Qzzxvv", "middle_name": null, "last_name": null, "name_type": "personal", "gender": null, "country": null, "sample_size": 0, "probability": 0, "took_ms": 1, "source": "none", "confidence": "unknown", "matched_as": null } ``` Example: Resolved by closest spelling — note the capped probability: ```json { "credits_charged": 1, "credits_remaining": 4819, "data_version": "2026.08", "request_id": "req_44a0be71c3925fd8", "query": "Micheal", "name": "Micheal", "first_name": "Micheal", "middle_name": null, "last_name": null, "name_type": "personal", "gender": "male", "country": null, "sample_size": 152388, "probability": 86, "took_ms": 2, "source": "fuzzy", "confidence": "high", "matched_as": "michael" } ``` ## Notes for this endpoint - Send the whole address. Only the local part is used: `john.doe@example.com` resolves as "John". - Role addresses (admin, info, sales, support, noreply and similar) and an initial followed only by a surname (`j.smith@example.com`) return `gender: null`. They still cost one credit each, so skip role addresses before sending when you can. - Read `probability` together with `sample_size` and `confidence`: 100 from 3 people is weaker than 85 from 90,000. Pick a threshold for this use case (for example `probability >= 80` and `confidence` of `high` or `medium`) and treat anything below it as unknown. - When `source` is `fuzzy` or `script`, check `matched_as` before accepting the result. `llm` answers only appear when `ai_fallback` is true; label them as less certain. - Use `first_name`, `middle_name` and `last_name` from the response instead of splitting names in your own code. They are returned even when `gender` is null and cost no extra credit. `last_name` is always null for usernames. - `name_type` is `organization` or `role` when the input is a company or a shared mailbox; those rows return `gender: null` and still cost a credit, so filter them out of lists before sending when you can. - Pass `country` whenever you know it. Some names change gender across borders: Andrea is male in Italy and female in Germany. Without it the answer is the worldwide aggregate. - Leave `best_guess` off unless you apply your own `probability` threshold afterwards; it returns a guess where the API would otherwise return null. - `ai_fallback` sends the value to a third-party AI provider and fails with 422 `ai_consent_required` until the account owner enables AI lookups in the dashboard. Leave it off unless the user asked for it. - Each call resolves one value and costs one credit, unknown results included. For lists, use `POST https://namegender.com/api/v1/gender/bulk`. ## Errors Every failure, at every status code, returns the same JSON body. Fields: `error`, `message`, `request_id`, `docs`, `errors`, `retry_after`. The HTTP status code is the success signal; there is no success flag in the body. Branch on `error`, never on `message`. ```json { "error": "no_credits", "message": "You are out of credits. Buy more or wait for your daily free quota to reset.", "request_id": "req_9c1f5b2a7e0d4a13", "docs": "https://namegender.com/docs#error-no_credits" } ``` | `error` | HTTP | Meaning | | --- | --- | --- | | `missing_key` | 401 | No API key was sent. Add an Authorization: Bearer header or an X-Api-Key header to the request. | | `invalid_key` | 401 | This API key is not valid. | | `revoked_key` | 401 | This API key has been revoked. | | `blocked` | 403 | This account has been suspended. Contact support. | | `email_not_verified` | 403 | This account's email address has not been confirmed yet. Open the confirmation link we emailed you, or request a new one from your dashboard. | | `ip_not_allowed` | 403 | Requests from this IP address are not allowed for this key. | | `proxy_secret_required` | 403 | This key only works through its API marketplace, which signs every request. Use the key issued to you there. | | `forbidden` | 403 | You are not allowed to perform this action. | | `no_credits` | 402 | You are out of credits. Buy more or wait for your daily free quota to reset. | | `missing_input` | 400 | The "" parameter is required. | | `invalid_input` | 422 | The "" parameter is not valid. | | `too_many_items` | 422 | A maximum of 100 items can be sent in one request. | | `ai_consent_required` | 422 | ai_fallback sends the name to a third-party AI provider, which this account has not agreed to. See the "ai" field for who that provider is, then enable AI lookups in your dashboard settings. | | `unknown_endpoint` | 404 | There is no endpoint at this path. Check the URL against the API documentation. | | `method_not_allowed` | 405 | This endpoint does not accept requests. | | `payload_too_large` | 413 | That request body is too large. | | `rate_limited` | 429 | Too many requests. Slow down and try again shortly. | | `batch_not_found` | 404 | There is no file job with this ID on this account. | | `batch_not_startable` | 409 | This job has already been started or closed. | | `batch_not_finished` | 409 | This job has not finished yet. Check its status and download the result once it is completed. | | `batch_in_progress` | 409 | This job is being processed and cannot be cancelled now. Delete it once it has finished. | | `result_gone` | 410 | This job has no result to download. It failed, was cancelled, expired, or its single-download result has already been fetched. | | `too_many_batches` | 429 | You already have 100 file jobs running. Wait for one to finish before starting another. | | `not_ready` | 503 | The name database is being rebuilt. Try again in a moment. | | `server_error` | 500 | Something went wrong on our side. We have been notified. | ## Implementation rules - **Keep the key on the server.** Read it from `NAMEGENDER_API_KEY`. Never put it in browser, mobile or desktop client code, in logs, or in URLs; send it in the `Authorization: Bearer` header. The API does not read keys from the query string or the request body. - **Do not keep names you do not need.** If the names are personal data, turn on "Don't store the names this key sends" for the key in the dashboard: the input and resolved name are then never written to the request history. Send POST so the names also stay out of web server access logs. - **Unknown is an answer, not an error.** HTTP 200 with `gender: null` means the evidence is insufficient. Store it as unknown. Do not replace it with a default gender, do not retry it, and do not raise an exception. - **Branch on `error`, never on `message`.** Messages are translated and can change. Treat an `error` value you do not recognise as a generic failure instead of crashing. - **Retry only what can succeed on retry.** On 429, wait the number of seconds in the `Retry-After` header (also `retry_after` in the body), then retry. On 503 and 500, retry at most 3 times with exponential backoff (for example 1 s, 2 s, 4 s). Never retry 400, 401, 402, 403, 404, 405, 413 or 422: fix the request, the key or the account instead. - **Stop on 402 `no_credits`.** Surface it to whoever runs the job. The daily free quota resets at midnight UTC; purchased credits stay on the balance until they are spent. - **Stay under the rate limit.** The default is 1200 requests per minute per API key. Watch `X-RateLimit-Remaining` and cap concurrency; do not fire unbounded parallel requests. - **Batch instead of looping.** For more than one value, use `POST https://namegender.com/api/v1/gender/bulk` with up to 100 values per request instead of calling a single-value endpoint in a loop. - **Set a client timeout** (for example 10 seconds). Lookups usually take a few milliseconds; a request that hangs should fail rather than block a worker. - **Encode input as UTF-8** and let the HTTP client build the query string or JSON body. Do not concatenate raw names into URLs: non-Latin names such as `محمد` or `中村` must be percent-encoded. - **Log `request_id`** (also returned as the `X-Request-Id` header) with every failure. You may send your own `X-Request-Id` to correlate calls with your tracing. - **Store `data_version` next to results** you persist, so a changed answer between two runs can be traced to a dataset update. - **Use results responsibly.** A name-based result is a statistical association, not a person's gender identity. Keep unknown results visible, let people correct their own data, and do not use inferred gender for employment, medical, financial, insurance, legal or eligibility decisions. ## Verify the integration - Send `john.doe@example.com` and confirm `name` in the response shows the first name that was extracted. - Send `admin@example.com` and `j.smith@example.com` and confirm both are stored as unknown, not as an error. - Call with an invalid key and confirm your code reports 401 `invalid_key` without retrying. - Simulate a 429 response with `Retry-After: 2` and confirm your code waits before retrying. - Search the client-side bundle and the logs for `ng_live_` and confirm the key does not appear.