Vietnamese name parser API

Split a Vietnamese full name into family, middle and given names, fix capitals, guess gender with a probability, suggest anh / chị and e-mail slugs.

GETPOSThttps://apibox.io.vn/v1/vn-name

Text▶ Try it online

Vietnamese names are written family name first (Nguyễn Văn Hùng) and people are addressed by the last word. The API normalises spacing and capitals (nguyễn văn HÙNG → Nguyễn Văn Hùng), splits family, middle and given names, including multi-word family names (Tôn Nữ, Tôn Thất, Âu Dương, Nguyễn Phước, Công Tằng Tôn Nữ), and detects names written in Western order (Hung Van Nguyen). It returns first_name / last_name for international forms, unaccented and upper-case forms for bank cards, initials, a URL slug and common corporate e-mail local parts (hungnv, hung.nguyen).

Gender is guessed with a probability from the middle name (Thị, Văn) and statistics of about 2,500 labelled given names (duyet/vietnamese-namedb, MIT licence, refreshed weekly). The answer also suggests a salutation (anh / chị, ông / bà, Chào chị Hương, Kính gửi Bà …); neutral names such as Anh or Linh return a lower confidence or unknown. Send names (array or one per line, up to 1,000) to process a list, and sort=true to sort it the Vietnamese way (given name, then middle, then family, with the Vietnamese alphabet).

The gender guess is statistical and should only be used for wording, never for decisions about a person. Nothing is stored.

Parameters

Name	In	Type	Required	Default
`name`	query\|body	string	yes		Full name (max 200 characters).
`names`	body	array	no		Up to 1,000 names (array, or a string with one name per line).
`order`	query\|body	string	no	`auto`	`auto`, `family_first` or `given_first`.
`sort`	query\|body	boolean	no	`false`	With `names`: sort in Vietnamese order.

Example

curl "https://apibox.io.vn/v1/vn-name?name=nguy%E1%BB%85n%20%20th%E1%BB%8B%20thu%20H%C6%AF%C6%A0NG" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-name?name=nguy%E1%BB%85n%20%20th%E1%BB%8B%20thu%20H%C6%AF%C6%A0NG', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-name?name=nguy%E1%BB%85n%20%20th%E1%BB%8B%20thu%20H%C6%AF%C6%A0NG",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-name?name=nguy%E1%BB%85n%20%20th%E1%BB%8B%20thu%20H%C6%AF%C6%A0NG');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "input": "nguyễn  thị thu HƯƠNG",
  "full_name": "Nguyễn Thị Thu Hương",
  "family_name": "Nguyễn",
  "middle_name": "Thị Thu",
  "given_name": "Hương",
  "first_name": "Thị Thu Hương",
  "last_name": "Nguyễn",
  "order_detected": "family_first",
  "word_count": 4,
  "unaccented": "Nguyen Thi Thu Huong",
  "upper_unaccented": "NGUYEN THI THU HUONG",
  "initials": "NTTH",
  "gender": "female",
  "gender_probability_female": 1,
  "gender_confidence": 1,
  "gender_evidence": [
    "middle name \"Thị\" (female)",
    "given name \"hương\": 0 male / 25 female names"
  ],
  "salutation": {
    "informal": "chị",
    "formal": "bà",
    "greeting_vi": "Chào chị Hương",
    "letter_vi": "Kính gửi Bà Nguyễn Thị Thu Hương"
  },
  "slug": "nguyen-thi-thu-huong",
  "email_local_parts": [
    "huongntt",
    "huong.nguyen",
    "nguyenthithuhuong"
  ],
  "sort_key": "kzspj xkl xky pjy}ip~11111111611111111141",
  "warnings": [],
  "source": "Gender statistics: duyet/vietnamese-namedb (MIT, © Van-Duyet Le), 1230 male / 1303 female names; updated 2026-11-11",
  "note": "Gender is a statistical guess from the name only; do not use it for decisions about a person."
}

Use cases

Personalise e-mails and SMS (“Chào chị Hương”)
Split full names into CRM first / last name fields
Sort class or staff lists by given name
Generate company e-mail addresses and unaccented card names

FAQ

How reliable is the gender guess?

Very high with Thị or Văn and for clearly gendered names; lower for neutral names (Anh, Linh, Minh), where the probability is close to 0.5 and gender may be unknown.

Which family names are recognised?

About 150 common surnames plus multi-word ones (Tôn Nữ, Tôn Thất, Âu Dương, Nguyễn Phước…). Unknown family names are kept and reported with a warning.

How does Vietnamese sorting work?

By given name first, then middle and family names, using the Vietnamese letter order (a ă â … d đ …) and tones, as schools do.

Vietnamese name parser API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics