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