POST /v1/parse
Parse a single phone number. Returns a JSON envelope with ok and a result object.
Request (JSON)
{
"input": "0039 333 123 4567",
"default_region": "IT",
"options": {
"format": ["e164","international","national","rfc3966"],
"classify": true,
"mask": { "mode": "none" },
"hash": { "enabled": false }
}
}
Options
- options.format: list of formats to include (always includes e164 in the UI).
- options.classify: include number type / classification when available.
- options.mask.mode: none, last2, last4.
- options.hash.enabled: include an HMAC-derived stable value (when enabled server-side).
Response (shape)
{
"ok": true,
"result": {
"valid": true,
"e164": "+393331234567",
"rfc3966": "tel:+39-333-123-4567"
},
"warnings": [],
"errors": []
}
The result object may include extra fields depending on enabled options and server configuration (e.g. international/national formats, region/type, masking/hash notes).
HTTP status & errors
- 200: request processed (check ok and result.valid).
- 400: malformed JSON / invalid parameters.
- 401/403: missing/invalid API key (when auth is enabled).
- 429: rate limited (see ratelimit headers).
- 5xx: transient server error.