API Reference

Phone Validation

Validate and normalize phone numbers using Google libphonenumber

Ensure phone numbers collected from users are real, properly formatted, and reachable. Built on Google's libphonenumber library, this API validates numbers across 200+ countries, normalizes them to E.164 format, and detects the carrier type — essential for SMS verification, CRM data quality, and international compliance.

libphonenumberbatch supportphone maskingmulti-format output

Endpoint

POST /v1/phone/validate
Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.
Open Swagger UI (interactive docs)

Request

{
  "rawInput": "+14165551234",
  "defaultRegion": "CA"
}

Request Fields

FieldTypeDescription
rawInput string Phone number in any format
defaultRegion string Default region code for parsing (ISO 3166-1 alpha-2)

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parseStatus": "SUCCESS",
  "valid": true,
  "overallDecision": "VALID",
  "countryCode": 1,
  "regionCode": "CA",
  "numberType": "MOBILE",
  "e164": "+14165551234",
  "formats": {
    "international": "+1 416-555-1234",
    "national": "(416) 555-1234",
    "e164": "+14165551234",
    "rfc3966": "tel:+1-416-555-1234"
  }
}

Response Fields

FieldTypeDescription
requestId string Unique request identifier
parseStatus string Field value
valid boolean Whether the input is valid
overallDecision string Field value
countryCode integer Field value
regionCode string Field value
numberType string Field value
e164 string Field value
formats object Nested object with properties

Error Codes

StatusMeaning
200Request completed successfully
400Bad request — invalid or missing parameters
401Missing or invalid X-API-Key header
429Rate limit exceeded — check Retry-After header
500Internal server error

Common Error Scenarios

400 Invalid phone format

Request that triggers this:

{"rawInput": "invalid"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid Phone Number", "status": 400, "detail": "The input 'invalid' could not be parsed as a phone number"}

How to fix: Provide a valid phone number with country code or set defaultRegion. Accept formats like +1-234-567-8900 or (234) 567-8900.

400 Missing region code

Request that triggers this:

{"rawInput": "2025551234"}

Error response:

{"type": "/problems/validation-error", "title": "Ambiguous Number", "status": 400, "detail": "Cannot determine country for number without explicit region code"}

How to fix: Either provide an international format (+1-202-555-1234) or set the defaultRegion field.

Code Examples

curl -X POST /v1/phone/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "rawInput": "+14165551234",
  "defaultRegion": "CA"
}' 
// Node.js (18+) or modern browser
const response = await fetch("/v1/phone/validate", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "rawInput": "+14165551234",
    "defaultRegion": "CA"
}),
});

const data = await response.json();
console.log(response.status, data);
import requests

response = requests.post(
    "/v1/phone/validate",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "rawInput": "+14165551234",
    "defaultRegion": "CA"
},
)

print(response.status_code)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "rawInput": "+14165551234",
  "defaultRegion": "CA"
}`)
	req, _ := http.NewRequest("POST", "/v1/phone/validate", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}
{
  "name": "phone_validation",
  "description": "Validate and normalize phone numbers using Google libphonenumber",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/phone/validate",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference