---
title: "Validate and score a phone number"
method: GET
path: "/v1/lookup/phone"
tags: ["Scoring"]
---

# Validate and score a phone number

`GET /v1/lookup/phone`

## Request

- Base URL: `https://www.layercall.com`
- URL: `https://www.layercall.com/v1/lookup/phone`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Parses the number, identifies line type (mobile, VoIP, premium rate, toll free) and carrier, and scores fraud risk.

## Query parameters

- `phone` string, required
- `country` string
- `strictness` 'lenient' | 'balanced' | 'strict'

## Response `200`

Result

- PhoneResult
  - `phone` string, required
  - `risk_score` integer, required: 0 = clean, 100 = certain fraud.
  - `verdict` 'allow' | 'review' | 'block', required: Recommended action. Thresholds move with `strictness`.
  - `parse_status` 'ok' | 'country_required' | 'impossible' | 'invalid_pattern': Distinguishes 'you omitted country' from 'this number is bad'.
  - `signals` object
    - `syntax_valid` boolean
    - `is_possible` boolean
    - `is_voip` boolean, nullable: In a range the national plan reserves for VoIP. null where the plan has no VoIP range (+1 US, India, Germany and others) or the number is only fixed-line-or-mobile: unknown, not no.
    - `is_premium_rate` boolean
    - `is_toll_free` boolean
    - `assigned_area_code` boolean, nullable: NANP only. null when not applicable.
  - `number` object
    - `e164` string, nullable
    - `country` string, nullable
  - `cached` boolean
  - `request_id` string
  - `processing_time_sec` number
  - `first_seen` unknown
  - `times_seen` integer
  - `abuse_reports` integer
  - `billable_lookups` integer

## Other responses

- `400`: Missing or malformed input.
- `401`: Missing, invalid, or revoked API key.
- `429`: Monthly quota or spend cap reached, or the 600 requests-per-minute rate limit exceeded.

---

[API](https://skmtc.dev/layercall/apis/layercall-api.md) · [All operations](https://skmtc.dev/layercall/apis/layercall-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layercall/apis/layercall-api/revisions/b1258307dc91?raw)