Number to Words API: The Complete Guide to Number Spelling

Need to spell out numbers for checks, legal documents, or accessibility? This guide covers everything you need to know about converting numbers to written words via API, including currency formatting and implementation examples in multiple languages.

What is Number to Words Conversion?

Number to words conversion transforms numeric values into their written text equivalents. For example, 123 becomes "one hundred twenty-three", and 1,000,000 becomes "one million".

This is essential for legal documents, checks, and accessibility where numbers must be spelled out to prevent fraud or improve comprehension.

Common Use Cases

Number to words conversion is required in several contexts:

Check Writing

Banks require amounts spelled out: "$1,234.56" becomes "One thousand two hundred thirty-four and 56/100 dollars".

Legal Documents

Contracts often require both numeric and written amounts for clarity and fraud prevention.

Accessibility

Screen readers may need numbers spelled out for better comprehension.

Using the Number to Words API

TinyFn provides a simple endpoint to convert numbers to words:

GET https://api.tinyfn.io/v1/format/number-to-words?number=1234567
Headers: X-API-Key: your-api-key

{
  "number": 1234567,
  "words": "one million two hundred thirty-four thousand five hundred sixty-seven",
  "locale": "en-US"
}

Parameters

Code Examples

JavaScript / Node.js

// Basic number to words
const response = await fetch(
  'https://api.tinyfn.io/v1/format/number-to-words?number=1234567',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { words } = await response.json();
console.log(words);
// one million two hundred thirty-four thousand five hundred sixty-seven

// Currency format for checks
const checkResponse = await fetch(
  'https://api.tinyfn.io/v1/format/number-to-words?number=1234.56¤cy=USD&capitalize=true',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { words: checkWords } = await checkResponse.json();
console.log(checkWords);
// One thousand two hundred thirty-four and 56/100 dollars

Python

import requests

# Basic number to words
response = requests.get(
    'https://api.tinyfn.io/v1/format/number-to-words',
    params={'number': 1234567},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['words'])
# one million two hundred thirty-four thousand five hundred sixty-seven

# Currency format
response = requests.get(
    'https://api.tinyfn.io/v1/format/number-to-words',
    params={'number': 1234.56, 'currency': 'USD', 'capitalize': 'true'},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['words'])
# One thousand two hundred thirty-four and 56/100 dollars

cURL

# Basic conversion
curl "https://api.tinyfn.io/v1/format/number-to-words?number=1234567" \
  -H "X-API-Key: your-api-key"

# Currency format
curl "https://api.tinyfn.io/v1/format/number-to-words?number=1234.56¤cy=USD&capitalize=true" \
  -H "X-API-Key: your-api-key"

Advanced Features

• Negative Numbers: Properly handles "negative" or "minus" prefix
• Decimals: Supports decimal numbers ("three point one four")
• Large Numbers: Handles billions, trillions, and beyond
• Ordinal Mode: Convert to ordinal words ("first", "second", "third")
• Year Mode: Format years naturally ("nineteen eighty-four")

Best Practices

1. Use currency mode for money: Properly formats cents/pence
2. Capitalize for formal documents: Start with capital letter
3. Validate input range: Very large numbers may exceed practical limits
4. Consider locale: "One billion" differs between US and UK

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-format": {
      "url": "https://api.tinyfn.io/mcp/format/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all formatting tools available via MCP in our Formatting MCP Tools for AI Agents guide.