Endpoint
GET https://requiems.xyz/v1/validation/phone
Validate Phone Number
Validates a single phone number and returns its country, type, formatted representation, carrier, and VOIP/virtual risk flags.
Parameters
| Name |
Type |
Required |
Location |
Description |
number |
string |
yes |
query |
The phone number to validate. Must include the country calling code (e.g. +12015551234). |
Response Example
{
"data": {
"number": "+447400123456",
"valid": true,
"country": "GB",
"type": "mobile",
"formatted": "+44 7400 123456",
"carrier": {
"name": "Three",
"source": "metadata"
},
"risk": {
"is_voip": false,
"is_virtual": false
}
},
"metadata": {
"timestamp": "2026-01-01T00:00:00Z"
}
}
Response Fields
| Field |
Type |
Description |
number |
string |
The original number as supplied in the request |
valid |
boolean |
Whether the number is a valid, dialable phone number |
country |
string |
ISO 3166-1 alpha-2 country code (omitted when valid is false) |
type |
string |
Number type: mobile, landline, landline_or_mobile, toll_free, voip, premium_rate, shared_cost, personal_number, pager, uan, voicemail, or unknown (omitted when valid is false) |
formatted |
string |
International format of the number, e.g. +44 7400 123456 (omitted when valid is false) |
carrier.name |
string |
Carrier name from phone prefix metadata (omitted when carrier cannot be determined) |
carrier.source |
string |
How the carrier was determined. Always "metadata" when present |
risk.is_voip |
boolean |
true when the number type is voip |
risk.is_virtual |
boolean |
true when the number is not tied to a physical SIM or fixed line: voip, personal_number, uan, pager, or voicemail |
Errors
400 bad_request — The number query parameter is missing.
1---
2name: phone-validation-get-phone
3api: Phone Validation
4method: GET
5path: /v1/validation/phone
6base_url: https://requiems.xyz
7description: Validates a single phone number and returns its country, type, formatted representation, carrier, and VOIP/virtual risk flags.
8---
9
10## Endpoint
11
12**GET https://requiems.xyz/v1/validation/phone**
13
14## Validate Phone Number
15
16Validates a single phone number and returns its country, type, formatted representation, carrier, and VOIP/virtual risk flags.
17
18## Parameters
19
20| Name | Type | Required | Location | Description |
21| ---- | ---- | -------- | -------- | ----------- |
22| `number` | string | yes | query | The phone number to validate. Must include the country calling code (e.g. +12015551234). |
23
24## Response Example
25
26```json
27{
28 "data": {
29 "number": "+447400123456",
30 "valid": true,
31 "country": "GB",
32 "type": "mobile",
33 "formatted": "+44 7400 123456",
34 "carrier": {
35 "name": "Three",
36 "source": "metadata"
37 },
38 "risk": {
39 "is_voip": false,
40 "is_virtual": false
41 }
42 },
43 "metadata": {
44 "timestamp": "2026-01-01T00:00:00Z"
45 }
46}
47```
48
49## Response Fields
50
51| Field | Type | Description |
52| ----- | ---- | ----------- |
53| `number` | string | The original number as supplied in the request |
54| `valid` | boolean | Whether the number is a valid, dialable phone number |
55| `country` | string | ISO 3166-1 alpha-2 country code (omitted when valid is false) |
56| `type` | string | Number type: mobile, landline, landline_or_mobile, toll_free, voip, premium_rate, shared_cost, personal_number, pager, uan, voicemail, or unknown (omitted when valid is false) |
57| `formatted` | string | International format of the number, e.g. +44 7400 123456 (omitted when valid is false) |
58| `carrier.name` | string | Carrier name from phone prefix metadata (omitted when carrier cannot be determined) |
59| `carrier.source` | string | How the carrier was determined. Always "metadata" when present |
60| `risk.is_voip` | boolean | true when the number type is voip |
61| `risk.is_virtual` | boolean | true when the number is not tied to a physical SIM or fixed line: voip, personal_number, uan, pager, or voicemail |
62
63## Errors
64
65- `400` **bad_request** — The number query parameter is missing.
gabrielmoreira