# Phone check

`POST /v1/phone/check` · **1 credit**

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `phone` | string | yes | The number as the person typed it. International format (`+44 7400 123456`) needs nothing else. |
| `country` | string | no | Two-letter country code (ISO 3166, e.g. `GB`) to read numbers typed in national format, like `07400 123456`. |

```bash [curl]
curl https://veqen-app.com/v1/phone/check \
  -H "Authorization: Bearer $VEQEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "07400 123456", "country": "GB"}'
```

```python [Python]
r = requests.post(
    "https://veqen-app.com/v1/phone/check",
    headers={"Authorization": f"Bearer {VEQEN_API_KEY}"},
    json={"phone": "07400 123456", "country": "GB"},
    timeout=10,
)
store(r.json()["e164"])  # "+447400123456"
```

```javascript [JavaScript]
const r = await fetch("https://veqen-app.com/v1/phone/check", {
  method: "POST",
  headers: { Authorization: `Bearer ${VEQEN_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "07400 123456", country: "GB" }),
});
```

## Response

```json
{
  "input": "07400 123456",
  "valid": true,
  "possible": true,
  "e164": "+447400123456",
  "international": "+44 7400 123456",
  "national": "07400 123456",
  "calling_code": 44,
  "country_code": "GB",
  "country": "United Kingdom",
  "location": "United Kingdom",
  "line_type": "mobile",
  "line_type_label": "Mobile",
  "carrier": "Three",
  "time_zones": ["Europe/Guernsey", "Europe/Isle_of_Man", "Europe/Jersey", "Europe/London"],
  "risk": { "score": 0, "level": "low", "verdict": "admit", "reasons": [] }
}
```

### Fields

| Field | What it tells you |
|---|---|
| `valid` | A real, assignable number for its country. Stronger than `possible`. |
| `possible` | The right length for the country, but maybe not an assigned range. |
| `e164` | **Store this.** The international standard form every SMS provider accepts. |
| `line_type` | `mobile`, `fixed_line`, `fixed_line_or_mobile` (some countries, like the US, don't separate them), `voip`, `toll_free`, `premium_rate`, `shared_cost`, `personal_number`, `pager`, `uan`, `voicemail` or `unknown`. |
| `carrier` | The carrier the number range was first assigned to. Numbers can be ported, so treat it as a hint. |
| `time_zones` | Where the number's range is used, handy for calling hours. |

### Risk reasons

| Code | Impact | Why |
|---|---|---|
| `unparseable_number` | 100 | Not a phone number, or missing the country code. |
| `invalid_number` | 85–95 | Wrong length, or a range no carrier uses. |
| `premium_rate_number` | 80 | Costs the caller money; never a personal phone. |
| `toll_free_number` | 60 | Belongs to a business. |
| `voip_number` | 50 | Cheap to create in bulk; common in fake signups. |
| `country_mismatch` | 15 | The number's country differs from the `country` you passed. |

## Frequently asked questions

### Does this send an SMS?

No. Validation uses numbering-plan data only (Google's libphonenumber). The number is never contacted.

### Can it detect every VoIP number?

It detects numbers in ranges assigned to VoIP. In countries without separate VoIP ranges, such as the US, VoIP numbers look like ordinary ones. Use SMS verification when it matters.