Salutation

Salutation for one name

Turns a name into a salutation line ready for a letter or email: "Sehr geehrte Frau Dr. Müller,", "Sayın Ahmet Bey,", "Madame,", "山田様". The gender lookup is included and the price is the same: one credit per name.

When the gender is not certain, the salutation is neutral. A wrong gender is worse than none, so the gendered form is used only when the gender is known with at least min_probability (default 90), and the language has what it needs (a surname for "Herr Müller", a given name for "Ahmet Bey"). form and reason say which form was chosen and why. best_guess and ai_fallback do not apply here. Companies and role addresses get the language's form for organisations.

post/api/v1/salutation

Request

  • Base URL: https://namegender.com
  • URL: https://namegender.com/api/v1/salutation
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key

Request body

namestring

Full name, titles included. Send this or first_name/last_name.

first_namestring

Given name, when your CRM keeps names in separate fields. No parsing is done.

last_namestring
emailstring

Email address, used when neither name nor first_name/last_name is sent. The name is read from the part before the @; role addresses such as info@ get the form for organisations. Addresses carry no accents, so anna.mueller@ greets Frau Mueller, not Müller.

languagestring

The language the salutation is written in: en, en-US, en-GB, de, de-AT, de-CH, fr, es, it, pt, pt-PT, pt-BR, nl, tr, pl, ja. When omitted, the language of locale, then the main language of the country, then en. An unsupported language is an error, never a silent fall back to English.

countrystring

Country hint for the gender lookup, as on the gender endpoints. It does not set the language when language is sent: write to Mr Müller in the US in English.

localestring
ipstring
gender'male' | 'female' | 'neutral'

Gender you already know. Overrides the lookup; neutral always gives the neutral form.

min_probabilityinteger

Lowest probability for a gendered salutation. Below it the neutral form is used.

titlestring

Academic title kept in a separate field. Used in German and English salutations.

Example request

{
  "name": "Dr. Anna Müller",
  "email": "anna.mueller@example.de",
  "language": "de",
  "title": "Dr."
}

Response

Salutation built.

credits_chargedinteger
credits_remaininginteger
data_versionstring nullable
request_idstring
country_source'country' | 'locale' | 'ip' | 'null' nullable
querystring
languagestring
form'gendered' | 'neutral' | 'organization'
reason'gender_unknown' | 'below_min_probability' | 'gender_neutral_requested' | 'no_surname' | 'no_given_name' | 'language_ungendered' | 'null' nullable

Why the neutral form was used. Null for gendered and organisation forms.

gender'male' | 'female' | 'null' nullable
gender_source'lookup' | 'input' | 'title' | 'null' nullable

input: the gender parameter. title: a courtesy title in the name (Frau, Mr). lookup: our dataset.

probabilityinteger nullable
confidencestring nullable
first_namestring nullable
last_namestring nullable
name_type'personal' | 'organization' | 'role'
countrystring nullable

Example response

{
  "language": "de",
  "salutation": {
    "formal": "Sehr geehrte Frau Dr. Müller,",
    "informal": "Liebe Anna,",
    "neutral": "Guten Tag Dr. Anna Müller,"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.