REST API Specification
Developer Phone Lookup API Reference
Inspect, format, and classify phone numbers with single-digit millisecond latency. Detect country codes, verify numbering-plan validity, classify mobile vs landline vs VoIP lines, and retrieve carrier attribution.
Interactive API Test Console
Live Production Endpoint
Execute a live request to /api/v1/lookup/ directly from your browser to inspect real response payloads.
Latency: -- ms
Response Payload • application/json
HTTP 200 OK
GET
POST
/api/v1/lookup/
Evaluates a single phone number. Accepts query parameters via GET, or JSON body via POST.
Request Parameters
| Field | Type | Requirement | Description |
|---|---|---|---|
| phone | string | Required | The raw phone number in international, E.164, or domestic national format. |
| country | string | Optional | 2-letter ISO country code (e.g. US, GB, DE) used as context when country dialing prefix is absent. Defaults to US. |
Example cURL Request
curl -s "https://smsriver.com/api/v1/lookup/?phone=%2B14155552671&country=US" \ -H "Authorization: Bearer YOUR_API_KEY"
POST
/api/v1/lookup/batch/
Evaluates a batch of up to 100 phone numbers in a single atomic HTTP round-trip.
Request Body (JSON)
{
"numbers": [
"+14155552671",
"+447911123456",
"+491512283200",
"+18005550199"
],
"default_country": "US"
}
Example Batch Response
{
"total_submitted": 4,
"valid_count": 4,
"invalid_count": 0,
"mobile_count": 3,
"other_line_count": 1,
"results": [
{
"raw_input": "+14155552671",
"formats": {
"e164": "+14155552671",
"international": "+1 415-555-2671",
"national": "(415) 555-2671",
"rfc3966": "tel:+14155552671"
},
"country_code": "US",
"country_name": "United States",
"dial_code": "+1",
"line_type": "mobile",
"line_type_label": "Mobile / Cellular",
"is_valid_format": true,
"carrier": "T-Mobile / AT&T Mobility"
}
]
}