Continue → Overview
NameGender
Sign up free
← API documentation

API changelog

Changes that can affect an integration or the answer it gets back: new endpoints and fields, behaviour changes and corrections to the name data. Each response carries data_version; when a result changes between two calls, compare it first, then look here.

Changes

  1. Data

    Japanese kanji names are read with Japanese readings

    In a Japanese context (country=JP, or kana alongside the kanji), kanji given names were looked up through Mandarin pronunciations, so 陽子 (Yōko) came back male as "yang zi". They are now read with Japanese given-name readings from JMnedict. A name with no known reading falls back to its last kanji when that kanji is strongly gendered: names ending in 斗, 翔 or 太 are mostly boys, in 菜 or 花 mostly girls. Kanji input without a Japanese context, such as Chinese names, is unchanged.

  2. Data

    Correct US counts restored for 6,779 common names

    An import error had overwritten the US counts of 6,779 of the most looked-up names with wrong figures: Charlie showed 2.8% female on 29,034 records against a true 17.3% on 219,878. Every US row now matches the official Social Security Administration files, so sample_size and, for some names, probability change for these names.

  3. Data

    Scotland and Northern Ireland birth counts added

    Counted birth registrations from Scotland and Northern Ireland now contribute to results for country=GB, alongside England and Wales.

  4. Added

    Webhooks

    Register an HTTPS endpoint in the dashboard to receive batch.completed, batch.failed, credits.low and credits.depleted events, plus webhook.test on demand. Deliveries are signed and retried. Receivers should answer 2xx to event types they do not handle, because new types can be added to v1.

  5. Added

    File API: /api/v1/batches

    Upload a CSV or XLSX file, let it process in the background and download the result with gender, probability, name part and name_type columns added. The same pipeline as dashboard file uploads, now available to API keys.

  6. Fixed

    Arabic-script names reach their dictionary entries

    Arabic script does not write short vowels, so transliteration produced forms such as "snan" for Sinan and missed names that were in the dataset with real counts. Lookups now restore the vowels before matching, which raises coverage for Arabic-script input.

  7. Fixed

    Revoking an API key now revokes it

    The revoke button in the dashboard reported success without disabling the key, so a revoked key kept working. Revocation now takes effect immediately. A key revoked before this date was never disabled and still appears as active in the dashboard; revoke any such key again.

  8. Added

    name_type on every lookup

    Every lookup returns name_type: personal, organization or role. Company names ("Acme LLC") and role mailboxes ("Customer Service") get gender null instead of a confident guess from their first word. personal means no organization or role marker was found; it does not confirm the input is a real name.

  9. Added

    First, middle and last name in every result

    Lookups return first_name, middle_name and last_name parsed from the input, at no extra credit and even when gender is null. "Smith, John" is now read surname first, and capital İ no longer leaves a stray combining dot in the returned name.

  10. Breaking

    API v1 contract

    All endpoints live under /api/v1; unversioned paths return 404. The API key is accepted only in the Authorization: Bearer or X-Api-Key header, never in the query string. Options are ai_fallback and best_guess. Responses carry credits_charged, credits_remaining, request_id and data_version, and the HTTP status code is the only success signal.

Versioning and deprecation

  • Every endpoint lives under /api/v1. A breaking change gets a new version prefix; it is not made to v1.
  • Additive changes can arrive in v1 without notice: new endpoints, new optional parameters, new response fields, new error codes and new webhook event types. Ignore fields you do not use, and answer 2xx to webhook events you do not handle.
  • Branch on the machine-readable error field, never on message: messages are translated and their wording can change.
  • Corrections to the name data change results without changing the contract. They are listed here as Data entries.
  • If a version is ever retired, the date is announced on this page and by email to account owners before it stops answering.

Reporting a security issue

Write to info@namegender.com with "security" in the subject. Include what you found and how to reproduce it; please do not test against other customers' data. The same contact is published in security.txt.