Continue → Overview
← 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. Fixed

    Less common Chinese surnames in surname-first pinyin

    A two-word pinyin name is read with the Chinese surname as the surname on either side, but the rule only knew the 97 most common surnames. "Jing Shang-Hua", "Teng Yue'e" and "Nie Ming-Ming" read the surname as the given name. 124 less common surnames (Ji, Qi, Qu, Nie, Zuo, Jing, Teng and others) are now recognised when the given name is written with a hyphen or an apostrophe. They are not used when both words have one syllable ("Fei Ke") or the given name is written as one word ("Jing Shanghua"), because syllables such as Jing, Ying and Ling are also common given names and some surnames from other languages look like fused pinyin (Mori, Souza); those inputs behave as before.

  2. Changed

    Rows with an empty name cell are free in files

    A file costs one credit per row that has a name. Rows whose name cell is empty were charged too; they now cost nothing, and credits_used on the job is the number actually charged. The estimate shown after an upload counts every row, so it is an upper bound. Repeated names are still one credit per row: they are looked up once for speed, not billed once.

  3. Added

    Courtesy titles decide the gender; new gender_source field

    A courtesy title in the input now decides the gender: "Mrs Smith" used to return male 97% from the statistics for Smith as a first name, "Herr Andrea" female 96%. When the name statistics agree with the title the statistical answer is kept; otherwise gender comes from the title with sample_size 0, confidence unverified, the probability cap used for uncounted data and matched_as set to the title. A title followed by one word reads that word as the surname (first_name null, last_name Smith). The new field gender_source says what decided the gender: lookup (the name, see source) or title; source keeps its existing values. This applies to /gender, /gender/bulk and /gender/email ("mr.smith@"), and salutations use the title and surname: "Sehr geehrte Frau Müller,", "Dear Mrs. Smith:". Polish Pan/Pani count as titles only with country=PL or before a full name, and Hr./Sig. only with the dot, because Pan, Sig and HR are also names or mailboxes.

  4. Fixed

    Placeholders in a name field get no gender

    Values such as "None", "N/A", "Not Provided", "Dear Customer", "First name", "Kunde", "Nom", "Prénom", "Vorname" and "Ad Soyad" returned a confident gender because some of these words appear as names in the long tail of the data. When the whole input is a placeholder, gender is now null and name_type is role, the same list the name check uses. A word inside a longer name ("Nom Dupont") is looked up as usual, and a single word with at least 100 counted people in the statistics is always treated as a name.

  5. Fixed

    Surname-first email addresses

    Email addresses were looked up by their first word only, so garcia.sofia@ returned male 93% from Garcia and schneider.anna@ with country=DE male 100%. The whole name in the address is now read with the same rules as /api/v1/gender: both return female, first_name Sofia or Anna, and salutations built from those addresses use the surname ("Estimada Sra. Garcia:").

  6. Fixed

    File row count shown before a job matches the rows read

    The row count and credit estimate shown after an upload are now the number of rows the job reads. They were one short for a CSV whose last line had no line break, and too high for files with blank lines, line breaks inside quoted cells, or blank rows in XLSX. CSV files with old Mac line endings (CR only) were read as one line and are now read row by row. XLSX headers and previews come from the first sheet, the one that is processed.

  7. Changed

    Age for an uncovered country returns no parsed name

    A request to /api/v1/age for a country without a birth series still costs nothing and returns reason country_not_covered, but first_name is now null. Name parsing is part of the paid endpoints.

  8. Changed

    country is null when the answer comes from worldwide data

    When you send a country hint but we hold no data for that name in that country, the answer comes from the worldwide figures. country used to repeat the hint anyway (Andrea with country=JP returned "JP" next to the worldwide sample size); it is now null, as the documentation and the OpenAPI schema already said. Answers that really are narrowed to a country are unchanged. If you stored country as "where the answer came from", rows written before today may name a country the data did not come from.

  9. Fixed

    Surname-first names in files and salutations

    In uploaded files, rows written surname first without a comma ("Dupont Jean" after "Dupont Marie") took the gender of the first row with the same surname; each row is now read on its own, so a file gives the same answers as /api/v1/gender/bulk, and first_name and last_name come from that row. Salutations placed the given name where the surname belongs ("Schneider Anna" gave "Sehr geehrte Frau Anna,"); they now give "Sehr geehrte Frau Schneider,".

  10. Fixed

    Excel files: Windows CSV, dates and blank headers

    CSV files saved by Excel on Windows (Windows-1252 rather than UTF-8) are now read correctly, so Jürgen, Renée and François are found instead of coming back unknown, and the result file is valid UTF-8; a UTF-8 byte order mark is skipped. Date cells and FALSE values in XLSX files are kept in the result (dates as YYYY-MM-DD) instead of being emptied. A column with a blank or repeated header can be processed under the name the upload screen suggests ("Column 2", "name (2)").

  11. Fixed

    Dotted initials are not read as a first name

    "J.R. Smith" returned the first name "J.r." with a confident gender. Dotted initials are now treated like any other initial: the answer is unknown and last_name is Smith, the same as for j.r.smith@example.com. "J.R. Robert Smith" still resolves to Robert.

  12. Fixed

    Neutral salutations keep the initial from an email address

    An address such as j.schmidt@example.de has an initial but no first name. The neutral salutation now keeps the initial: "Guten Tag J. Schmidt," and "Dear J. Smith:" instead of "Guten Tag Schmidt,". first_name stays null, because an initial is not a first name.

  13. Added

    Age endpoint: /api/v1/age

    Returns how old the living people with a first name are: the median age, the middle half (age_range) and the middle 80% (age_range_80), from registered births and cohort survival. Covered: the United States, France and Norway; another country returns reason country_not_covered and costs nothing. An optional gender restricts the records to one gender. One credit per name; /api/v1/age/bulk takes up to 100.

  14. Changed

    Country names accepted as a country hint

    country accepts the country name in the main languages as well as the code: Germany, Deutschland and DE give the same answer, and UK is read as GB. CRM fields such as HubSpot's Country can be mapped as they are. Before this, the gender endpoints ignored a name without saying so and name-check answered 422.

  15. Added

    Salutations from an email address

    The salutation endpoint accepts email when there is no name: anna.mueller@example.de in German gives "Sehr geehrte Frau Mueller,". The bulk endpoint takes type email. Role addresses such as info@ get the language's form for organisations; in Italian and Japanese, which normally name the organisation, that is "Spettabile Azienda," and "ご担当者様". Email addresses carry no accents, so prefer a stored name when you have one. Requests with a name are unchanged.

  16. Added

    Name check endpoint: /api/v1/name-check

    Says whether a name typed into a sign-up or lead form looks like a real person's name, and why: keyboard mashing ("asdf qwerty"), placeholders ("Test Test", "John Doe", "n/a"), fictional characters ("Mickey Mouse"), profanity, digits, symbols and email addresses in the name field. The response is an assessment (plausible, suspicious or implausible), a score from 0 to 100 and the signals behind it; it never calls a name fake. A first name found in official birth records raises the score. Tested on 4,610 real first names in nine scripts with no false alarms. One credit per name; a bulk version takes up to 100 names.

  17. Fixed

    Accented names are no longer mistaken for role addresses

    A name that matches a role word only once its accents are removed, such as the Vietnamese given name "Thể" (which folds to "the"), was classified as name_type role and returned no gender. Role words are now matched only against unaccented input. Plain role inputs such as "info" or "admin" are unchanged.

  18. Fixed

    Turkish names keep their dotless ı in first_name and last_name

    A Turkish name sent in capitals, such as "AHMET YILMAZ", came back as "Yilmaz" because the general rule lowercases I to i. When country is TR or AZ, or the name contains a letter that only Turkish uses (ı, İ, ş, ğ), first_name, middle_name and last_name now follow Turkish casing: Yılmaz, İsmail. Without either signal a capital I cannot be told apart from the English or German one, so those names are unchanged. Gender results are not affected.

  19. Added

    Salutation endpoint: /api/v1/salutation

    Turns a name into a salutation ready for a letter or email in ten languages: English (US and UK), German (including Swiss), French, Spanish, Italian, Portuguese (Portugal and Brazil), Dutch, Turkish, Polish and Japanese. "Dr. Anna Müller" in German gives "Sehr geehrte Frau Dr. Müller,", "Ahmet Yılmaz" in Turkish "Sayın Ahmet Bey,". The gender lookup is included and the price is the same, one credit per name. The gendered form is used only when the gender is known with at least min_probability (default 90) and the language has the name part it needs; otherwise the response gives the neutral form and says why. A bulk version takes up to 100 names. Existing endpoints are unchanged.

  20. Added

    Country from a language tag or an IP address: locale, ip and country_source

    The gender endpoints and the bulk endpoint accept locale, a language tag such as it-IT or pt_BR, and ip, the end user's IP address. When country is not sent, the tag's region is used as the country, and when there is no regional tag either, the country of the IP address; a sign-up form can pass the browser language and get the Italian answer for Andrea. A tag without a region, such as en, sets no country. The IP address is used for the lookup only and is not stored; IP geolocation by DB-IP. Responses carry country_source: country, locale, ip, or null when the answer is worldwide. Requests without these parameters behave as before.

  21. 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.

  22. 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.

  23. 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.

  24. 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.

  25. 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.

  26. 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.

  27. 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.

  28. 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.

  29. 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.

  30. 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.