{"openapi":"3.1.0","info":{"title":"DearWho Name Check API","description":"Given a first name, returns the likely gender, a male probability, a per-country breakdown and ready-made salutations. Free, no API key.","version":"1.0.0","license":{"name":"GFDL-1.3 (derived name data)","url":"https://www.gnu.org/licenses/fdl-1.3.html"}},"servers":[{"url":"https://dearwho.vercel.app"}],"paths":{"/api/check":{"get":{"operationId":"checkName","summary":"Check whether a first name is usually male or female","description":"Looks up a single first name (Latin script or Chinese) and returns the verdict, male probability, per-country breakdown, ready-made English and German salutations, and a citation URL for the corresponding name page.","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"A first name in any script, e.g. Andrea, Kim, 张伟"}],"responses":{"200":{"description":"Name found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"404":{"description":"Name not found in the dataset"}}},"post":{"operationId":"checkNamesBulk","summary":"Check up to 200 first names in one request","description":"Bulk variant of GET /api/check: takes a list of first names and returns a compact verdict for each, in the same order, without the greeting or full country table.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["names"],"properties":{"names":{"type":"array","maxItems":200,"items":{"type":"string"},"description":"First names to check, e.g. [\"Andrea\", \"Kim\", \"Wei\"]. Max 200 per request."}}}}}},"responses":{"200":{"description":"One result per input name, in the same order","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkResultItem"}},"disclaimer":{"type":"string","description":"Statistical-estimate caveat applying to every result above; not a statement about the gender, identity or correct form of address of any particular person."}}}}}},"400":{"description":"Missing or malformed `names` field"},"413":{"description":"More than 200 names in one request"}}}},"/api/greeting":{"post":{"operationId":"generateGreeting","summary":"Generate the right email salutation for a full name","description":"Given a full name, formality level and target language, returns a ready-to-use salutation (e.g. \"Dear Mr. Rossi,\"), resolving the gender automatically from the given name unless one is supplied.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fullName","lang","formality","gender"],"properties":{"fullName":{"type":"string","maxLength":200,"description":"e.g. \"Andrea Rossi\""},"lang":{"type":"string","enum":["en","de","fr","es","it","pt","nl","zh","ja","ko","tr"]},"formality":{"type":"string","enum":["formal","neutral","friendly"]},"gender":{"type":"string","enum":["auto","male","female","neutral"]},"familyFirst":{"type":"boolean","description":"Explicit override; auto-detected when omitted."}}}}}},"responses":{"200":{"description":"Salutation plus the alternates for the other genders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GreetingResult"}}}},"400":{"description":"Missing or invalid field"}}}}},"components":{"schemas":{"CheckResult":{"type":"object","properties":{"query":{"type":"string"},"kind":{"type":"string","enum":["latin","chinese"]},"canonicalSlug":{"type":"string"},"record":{"type":"object","properties":{"name":{"type":"string"},"verdict":{"type":"string","enum":["male","mostly_male","unisex","mostly_female","female","country_dependent"]},"p":{"type":"number","description":"Probability the bearer is male, 0..1"},"confidence":{"type":"string","enum":["high","medium","low"]},"countries":{"type":"array","items":{"type":"object","properties":{"cc":{"type":"string"},"f":{"type":"integer","description":"Frequency 1..13"},"p":{"type":"number"}}}}}},"greeting":{"type":"object","properties":{"en":{"type":"string"},"de":{"type":"string"}}},"url":{"type":"string","description":"The English /name/<slug> page for this result"},"urlDe":{"type":"string","description":"The German /de/name/<slug> page for this result"},"source":{"type":"string","description":"Human-readable provenance and page URL for citation"},"disclaimer":{"type":"string","description":"Statistical-estimate caveat: not a statement about the gender, identity or correct form of address of any particular person, with a link to the privacy policy."}}},"BulkResultItem":{"type":"object","properties":{"query":{"type":"string"},"slug":{"type":["string","null"]},"name":{"type":"string"},"verdict":{"type":["string","null"]},"gender":{"type":["string","null"]},"p":{"type":["number","null"]},"confidence":{"type":"string","enum":["high","medium","low","none"]},"topCountry":{"type":["string","null"]},"url":{"type":"string","description":"Present only when the name was found"},"source":{"type":"string","description":"Present only when the name was found"}}},"GreetingResult":{"type":"object","properties":{"salutation":{"type":"string"},"usedGender":{"type":"string","enum":["male","female","neutral"]},"givenName":{"type":"string"},"familyName":{"type":"string"},"familyFirst":{"type":"boolean"},"confidence":{"type":"string","enum":["high","medium","low","none"]},"note":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string","description":"Statistical-estimate caveat: not a statement about the gender, identity or correct form of address of any particular person, with a link to the privacy policy."}}}}}}