SSN Format API: The Complete Guide to Social Security Number Formatting

Need to display Social Security Numbers securely while maintaining usability? This guide covers everything you need to know about formatting and masking SSNs via API, including security best practices and implementation examples.

What is SSN Formatting?

SSN formatting involves converting raw Social Security Number digits into properly formatted and optionally masked strings. The standard US SSN format is XXX-XX-XXXX, and masking typically shows only the last 4 digits.

For example, "123456789" becomes "123-45-6789" (formatted) or "XXX-XX-6789" (masked).

Masking Patterns

Different contexts require different levels of masking:

Full Mask (Most Secure)

XXX-XX-XXXX - Shows no digits. Used when SSN existence needs confirmation without revealing any part.

Last 4 (Common)

XXX-XX-6789 - Shows only last 4 digits. Standard for customer service and verification.

First 5 Masked

XXX-XX-6789 - Same as last 4, most widely used pattern for secure display.

Using the SSN Format API

TinyFn provides a simple endpoint to format and mask SSNs:

POST https://api.tinyfn.io/v1/format/ssn
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "ssn": "123456789",
  "mask": true
}

{
  "formatted": "XXX-XX-6789",
  "masked": true,
  "lastFour": "6789",
  "valid": true
}

Parameters

Code Examples

JavaScript / Node.js

// Mask SSN (default - show last 4)
const response = await fetch(
  'https://api.tinyfn.io/v1/format/ssn',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ ssn: '123456789', mask: true })
  }
);
const { formatted, lastFour } = await response.json();
console.log(formatted); // XXX-XX-6789
console.log(lastFour);  // 6789

// Format only (no masking - use with caution!)
const formatResponse = await fetch(
  'https://api.tinyfn.io/v1/format/ssn',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ ssn: '123456789', mask: false })
  }
);
const { formatted: full } = await formatResponse.json();
console.log(full); // 123-45-6789

Python

import requests

# Mask SSN
response = requests.post(
    'https://api.tinyfn.io/v1/format/ssn',
    json={'ssn': '123456789', 'mask': True},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(data['formatted'])  # XXX-XX-6789
print(data['lastFour'])   # 6789

# Custom masking (show last 2 only)
response = requests.post(
    'https://api.tinyfn.io/v1/format/ssn',
    json={'ssn': '123456789', 'mask': True, 'visibleDigits': 2},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['formatted'])  # XXX-XX-XX89

cURL

# Mask SSN
curl -X POST "https://api.tinyfn.io/v1/format/ssn" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ssn": "123456789", "mask": true}'

# Custom mask character
curl -X POST "https://api.tinyfn.io/v1/format/ssn" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ssn": "123456789", "mask": true, "maskChar": "*"}'

Common Use Cases

• Account Verification: Display last 4 digits for identity confirmation
• Tax Documents: Show SSN on W-2s and tax forms
• Customer Support: Verify identity without exposing full SSN
• Audit Logs: Log masked SSN for compliance without storing PII
• Data Export: Redact SSNs in exported reports

Security Best Practices

1. Always mask by default: Never display full SSNs unless legally required
2. Encrypt at rest: Store SSNs encrypted in your database
3. Limit access: Restrict who can see even masked SSNs
4. Audit access: Log all SSN access for compliance
5. Use HTTPS: Never transmit SSNs over unencrypted connections

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.