Number to Words API

Spell numbers and money amounts in Vietnamese or English words for invoices and receipts: VND, USD, decimals, negatives, up to 21 digits.

GETPOSThttps://apibox.io.vn/v1/number-to-words

Text▶ Try it online

The Number to Words API turns 1250000 into “Một triệu hai trăm năm mươi nghìn đồng” or “one million two hundred fifty thousand”. It follows the reading rules that are easy to get wrong in Vietnamese: “mốt” and “lăm” (21 → hai mươi mốt, 15 → mười lăm), “lẻ/linh” for a zero tens digit (105 → một trăm lẻ năm), “không trăm” inside large numbers (1,000,005 → một triệu không trăm lẻ năm) and the repeating “nghìn tỷ, triệu tỷ” scale.

Set currency=VND to append “đồng” (no decimals allowed) or currency=USD for “đô la Mỹ … xu” / “dollars and … cents”. Without a currency, decimals are read after “phẩy” or “point”. thousand=ngàn and odd=linh switch to the Southern / formal variants, and the first letter is capitalised unless capitalize=false.

The input is forgiving: 1250000, 1,250,000.50, 1.250.000 (Vietnamese thousand separators), 1 250 000 and a trailing đ or VND are all understood. The normalised number is returned so you can check how it was read. A single dot is always a decimal point.

Parameters

Name	In	Type	Required	Default
`number`	body\|query	string	yes		The number, e.g. `1250000`, `1,250,000.50`, `1.250.000` or `-12.5`.
`lang`	body\|query	string	no	`vi`	`vi` or `en`.
`currency`	body\|query	string	no		`VND` or `USD` (empty: plain number).
`thousand`	body\|query	string	no	`nghìn`	Vietnamese word for thousand: `nghìn` or `ngàn`.
`odd`	body\|query	string	no	`lẻ`	Vietnamese word for a zero tens digit: `lẻ` or `linh`.
`capitalize`	body\|query	boolean	no	`true`	Capitalise the first letter.

Example

curl "https://apibox.io.vn/v1/number-to-words?number=1250000&currency=VND" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/number-to-words?number=1250000&currency=VND', {
  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/number-to-words?number=1250000&currency=VND",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/number-to-words?number=1250000&currency=VND');
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

{
  "number": "1250000",
  "lang": "vi",
  "currency": "VND",
  "text": "Một triệu hai trăm năm mươi nghìn đồng"
}

Use cases

Print the amount in words on invoices, receipts and payment vouchers
Generate contracts with the amount written in full
Read numbers aloud in voice and accessibility features
Check amounts typed in words against the figures

FAQ

How is 1,000,005 read in Vietnamese?

“Một triệu không trăm lẻ năm”. Groups below the first non-zero group are read in full (“không trăm”) and a zero tens digit becomes “lẻ” (or “linh” with odd=linh).

How large can the number be?

Up to 21 integer digits (hundreds of quintillions; “trăm tỷ tỷ” in Vietnamese) and 10 decimal digits.

Does it use “nghìn” or “ngàn”?

“nghìn” by default, as in most invoicing software; pass thousand=ngàn for the Southern form.

Number to Words API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics