---
title: "Validate a phone number"
method: POST
path: "/phone"
tags: ["Phone"]
---

# Validate a phone number

`POST /phone`

## Request

- Base URL: `https://app.1lookup.io/api/v1`
- URL: `https://app.1lookup.io/api/v1/phone`
- Auth: HTTP bearer

Confirms a phone number is real and returns line type, carrier type, porting and, for US and Canada numbers, reachability and DNC/DNO flags. Numbers in other countries are checked against the numbering plan of their country. Costs 1 credit; an invalid number outside the US and Canada costs nothing.

## Request body

- object
  - `phone_number` string, required: Phone number to validate. E.164 format recommended.
  - `bypass_cache` boolean: Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual.

## Response `200`

Lookup completed. `metadata.credits_used` says what it cost.

- object
  - `success` true, required
  - `data` PhoneResult, required: Phone validation result. US and Canada numbers are checked against carrier records; numbers in other countries against their numbering plan, which leaves the US-only fields null.
    - `request` LookupRequest, required
      - `id` string, uuid, required: Id of this lookup.
      - `type` string, required: Lookup type, such as `phone`, `email` or `hlr_lookup`.
      - `input` string, required: The input as it was looked up, after normalization.
      - `timestamp` string, date-time, required: When the lookup ran.
      - `processing_time_ms` integer, required: Server-side processing time, in milliseconds.
    - `risk_assessment` RiskAssessment
      - `fraud_score` number: 0 to 100, higher is riskier. Not returned by every product (phone validation has none).
      - `risk_level` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required
      - `risk_factors` string[], required: Codes for what raised the risk, such as `NOT_REACHABLE`, `DISPOSABLE_EMAIL` or `NO_MATCH_FOUND`.
      - `confidence_level` number, required: 0 to 100.
    - `classification` object, required
      - `line_type` 'MOBILE' | 'LANDLINE' | 'VOIP' | 'TOLL_FREE' | 'PREMIUM' | 'UNKNOWN', required
      - `carrier_type` 'MAJOR_CARRIER' | 'REGIONAL_CARRIER' | 'VOIP_PROVIDER' | 'INTERNATIONAL_CARRIER' | 'UNKNOWN', required
      - `number_status` 'ACTIVE' | 'INACTIVE' | 'INVALID' | 'VALID' | 'UNKNOWN', required: US and Canada: ACTIVE, INACTIVE or INVALID from the carrier record, UNKNOWN for a toll-free number the record does not cover. Other countries: VALID or INVALID.
      - `portability_status` 'PORTED' | 'NOT_PORTED' | 'POSSIBLY_PORTED', required
      - `service_type` 'POSTPAID' | 'LANDLINE' | 'TOLL_FREE' | 'UNKNOWN', required
      - `connection_quality` 'EXCELLENT' | 'GOOD' | 'POOR' | 'UNKNOWN', required
      - `coverage` 'international': Only on numbers outside the US and Canada.
      - `country_code` string, nullable: ISO country code. Only on numbers outside the US and Canada.
    - `insights` object, required
      - `location` object
        - `timezone` string, nullable: Time zone of the number's area, or UNKNOWN.
        - `country` string, nullable: Country name. Only on numbers outside the US and Canada.
        - `country_code` string, nullable: ISO country code. Only on numbers outside the US and Canada.
        - `regions` string[]: Regions the number range belongs to. Only on numbers outside the US and Canada.
      - `carrier` object: Only on numbers outside the US and Canada. For US and Canada numbers the carrier name is `raw_api_fields.network`.
        - `name` string, nullable: Network name.
        - `mcc` string, nullable: Mobile country code.
        - `mnc` string, nullable: Mobile network code.
      - `routing` object, required
        - `lrn` string: Location routing number, or N/A.
        - `original_number` string
        - `is_ported` boolean, nullable: null when porting is possible but unconfirmed.
        - `port_type` union
          - integer
          - string
      - `reachability` object, required
        - `is_reachable` boolean, nullable: null when reachability was not checked: toll-free numbers, and numbers outside the US and Canada.
        - `reachable_status` union: Raw reachability flag from the record.
          - integer
          - string
          - boolean
        - `verification_method` string
        - `reason` string
      - `compliance` object, required
        - `dnc_listed` boolean, nullable: On the US Do Not Call list. null outside the US and Canada.
        - `dnc_status` 'LISTED' | 'NOT_LISTED' | 'NOT_APPLICABLE'
        - `dno_flag` boolean, nullable: Do Not Originate flag. null outside the US and Canada.
        - `number_quality` 'GOOD' | 'POOR'
        - `good_number` boolean
      - `risk_indicators` object, required
        - `voip_detected` boolean
        - `burner_probability` number: 0 to 1.
      - `raw_api_fields` object: The underlying carrier record: `number`, `lrn`, `network` (carrier name), `class` (line class: W mobile, L landline, V VoIP), `country` and related routing fields.
    - `recommendations` Recommendations, required
      - `primary_action` 'APPROVE' | 'VERIFY' | 'REVIEW' | 'BLOCK', required
      - `secondary_actions` string[], required
      - `user_message` string, required: One plain sentence describing the result.
      - `business_rules` object, required: Product-specific yes/no rules, such as `sms_allowed` and `voice_allowed` for a phone number.
    - `metadata` LookupMetadata, required
      - `api_version` string, required
      - `schema_version` string, required
      - `credits_used` integer: Credits this call cost. 0 for a no-match on success-billed products, and for a cached result you ran yourself.
      - `credits_remaining` integer: Credits left on the account after this call.
      - `cache_hit` boolean, required: True when the result came from the 7-day cache.
      - `cached_at` string, date-time: When the cached result was first looked up. Only on cache hits.
      - `data_sources` string[], required: Generic labels for the kinds of data consulted.
      - `fallback_used` boolean: Email verification only: a second verification ran.
      - `lookup_source` 'standard' | 'premium': Reverse phone lookup only: which record was read.

## Other responses

- `400`: `INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged
- `401`: `UNAUTHORIZED`: Invalid or missing API key
- `402`: `INSUFFICIENT_CREDITS`: Not enough credits for the request
- `403`: `UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan
- `429`: `RATE_LIMIT_EXCEEDED`: Too many requests
- `500`: `INTERNAL_ERROR`: Internal server error
- `503`: `SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds

---

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