# NameGender API: Resolve many names in one request

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#bulk.

## Your task

- Integrate `POST https://namegender.com/api/v1/gender/bulk` 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 <key>`.
- `X-Api-Key: <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

- `POST https://namegender.com/api/v1/gender/bulk` with a JSON body

Exists so that 100 names do not cost 100 HTTP round trips. Names are resolved in a single batch lookup. Credits are checked for the whole batch up front: either every name is processed or none is.

## Request

Send a JSON body with `Content-Type: application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `names` | string[] | yes | The values to resolve, each at most 200 characters. Each one costs one credit. 1–100 items. |
| `country` | string | no | ISO-3166 alpha-2 code applied to every value in the batch. Exactly 2 characters. |
| `type` | string | no | How to read the values in `names`. One of `name`, `email`, `username`. Default `name`. |
| `ai_fallback` | boolean | no | Ask a language model for values the dataset cannot answer. Requires AI lookups to be enabled in account settings; otherwise the batch fails with `ai_consent_required`. Default `false`. |
| `best_guess` | boolean | no | Return the most likely gender even below the confidence threshold, instead of null. For `email` and `username` batches it applies to the extracted first name. Default `false`. |

## Example requests

```bash
curl -X POST "https://namegender.com/api/v1/gender/bulk" \
  -H "Authorization: Bearer $NAMEGENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names":["Ayşe","Mehmet","Andrea"],"country":"TR"}'
```

## Response

HTTP 200. Every name resolved. Results are returned in the order they were sent.

| 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. |
| `took_ms` | integer | Whole milliseconds spent resolving the batch on our side, network time excluded. |
| `summary` | object | Counts for the whole batch. |
| `summary.total` | integer | Values sent. |
| `summary.identified` | integer | Values with a non-null `gender`. |
| `summary.unknown` | integer | Values with `gender: null`. |
| `summary.match_rate` | number | Percentage identified. |
| `results` | object[] | Same order as the names you sent. |
| `results[].query` | string | The input exactly as you sent it. |
| `results[].name` | string \| null | The first name actually looked up, after stripping titles and surnames. |
| `results[].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`. |
| `results[].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. |
| `results[].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. |
| `results[].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`. |
| `results[].gender` | string \| null | null means the dataset has no confident answer. This is not an error. One of `male`, `female`, `null`. |
| `results[].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. |
| `results[].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. |
| `results[].country` | string \| null | The country the answer came from, when narrowed. |
| `results[].took_ms` | integer | Whole milliseconds spent resolving this value on our side; network time is not included. |
| `results[].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`. |
| `results[].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`. |
| `results[].matched_as` | string \| null | For `fuzzy` and `script` sources, the dictionary entry that was actually matched. Always inspect this before accepting a fuzzy result. |

## Notes for this endpoint

- Send at most 100 values per request. Split longer lists into chunks of 100 and send the chunks sequentially or through a small bounded worker pool.
- Set `type` to `email` or `username` when the values are not names. One request cannot mix types. Role addresses and placeholder handles return `gender: null` but still cost a credit, so skip them before sending.
- `results` come back in the order you sent them. Join them to your records by position.
- Credits are checked for the whole batch before any work starts: a 402 means nothing in that batch was processed or charged, so the whole chunk can be resent after topping up.
- Every value costs one credit, unknown results included. Remove duplicates before sending and map the answers back afterwards.
- 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.

## 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 "<field>" parameter is required. |
| `invalid_input` | 422 | The "<field>" 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 <METHOD> 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 a list of 101 values and confirm your code splits it into two requests.
- Include a nonsense value such as `Qzzxvv` and confirm it is stored as unknown while the rest of the batch succeeds.
- 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.