POST AI agent ready /v1/number/spell

Number to Words API - Spell Numbers in English

Converts a numeric value into its English word form. Handles negative numbers, decimals, and values up to the billions. Decimals are spelled digit-by-digit after "point" (e.g., 3.14 becomes "three point one four"). Pass a locale hint to mark output intent; non-English locales return English spelling with a note, since only English is currently supported.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/number/spell \
  -H "Content-Type: application/json" \
  -d '{"number":1234.56,"locale":"en"}'

When to use this API

Print check amounts

Checks require the amount in words as a fraud control. Convert 1523.45 to "one thousand five hundred twenty-three point four five" before rendering the PDF.

Legal contracts and invoices

Many jurisdictions require figures to be written both numerically and in words. Auto-generate the word form so templates stay consistent across thousands of documents.

Screen readers and accessibility

Some assistive tech mispronounces long numeric strings. Ship the spelled-out form as aria-label text to guarantee a natural read-aloud for prices or IDs.

Voice prompts in IVR systems

Generate TTS-ready copy for amounts, confirmation numbers, or statistics without relying on the voice engine's built-in number handling, which varies by vendor.

Frequently asked questions

What is the maximum supported number?

Integers up to 999 billion (999,999,999,999) spell cleanly across thousand, million, and billion groups. Larger values return but omit higher scales. For finite inputs only; NaN and Infinity return a 400.

How are decimals handled?

The integer portion spells normally. After "point", each decimal digit is read individually, so 3.14 becomes "three point one four" and 0.05 becomes "zero point zero five". This matches how amounts are read aloud in English-speaking regions.

Are negative numbers supported?

Yes. The output is prefixed with "negative", so -42 becomes "negative forty-two".

Which locales are supported?

English only. The API accepts a locale parameter for forward compatibility, but any value other than "en" returns the English spelling with an "(English spelling)" note so you can detect and handle it in your UI.

Does it handle ordinals like "first" or "twenty-third"?

No. The endpoint returns cardinal numbers only. Post-process the output if you need ordinal forms.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.