Phone Number Intelligence and Validation API

Category Security

Endpoints 2

Key Features 7

Frequently Asked Questions 6

Trust signals before you integrate

Transparent docs, authenticated requests, and visible reliability details make it easier to evaluate DomScan before you ship.

Live Service status

Check live service health and documented failure responses before you integrate.

OpenAPI API artifacts

OpenAPI, Swagger, Postman, CLI, SDK, and MCP links are one click away.

API keys Protected access

Authenticated endpoints use API keys with clear credit costs before you call them.

10,000 Free allowance

Start with 10,000 monthly credits and upgrade only when usage grows.

What this API helps you ship

Use this page as a production brief: endpoints, examples, response shape, and the workflow pieces needed to plug DomScan into your own product.

Product workflows

Embed domain checks, DNS intelligence, risk signals, or enrichment into onboarding, search, and internal tools.

Analyst automation

Replace repeated manual lookups with scheduled jobs, alerting, and reproducible investigation steps.

Clean JSON data

Use predictable fields, documented status codes, and credit costs instead of scraping provider pages.

AI and ops tooling

Feed agents, dashboards, SOAR playbooks, and CRMs through OpenAPI, SDK, Postman, or MCP.

Integration workflow

A simple path from first request to repeatable production usage.

Authenticate once

Send your API key with the documented header and keep requests consistent across services.

Query with examples

Start from the curl and HTTP samples, then map the parameters into your application code.

Operate and monitor

Use status codes, credit costs, and response fields to build retries, logs, and alerts.

Developer kit

Jump from this page into machine-readable docs, request collections, SDKs, or agent tooling.

OpenAPI schema

Generate clients or inspect every request and response shape.

Postman collection

Import ready-made requests for manual testing and team handoff.

SDKs and CLI

Use maintained packages and command-line workflows instead of writing boilerplate.

MCP integration

Expose domain intelligence to AI agents and internal assistant workflows.

Parameters and response map

Scan the inputs, output fields, and status codes before wiring the endpoint into your client.

Request parameters

Parameter

phonedefault_countryexpected_countrydialing_from_countrylanguagephones

Response fields

Example Response

inputnormalized_inputkindvalidpossiblestatusrecommendationvalidation_levelreasonwarningsnumbernumber.e164

Status coverage

HTTP Status Codes

200400401402429500502503504

Endpoints

POST /v1/phone/validate

Credits: 1Authentication: Authentication required

phonedefault_countryexpected_countrydialing_from_countrylanguage

POST /v1/phone/validate/bulk

Credits: 1Authentication: Authentication required

phonesdefault_countryexpected_countrydialing_from_countrylanguage

Trust signals before you integrate

Transparent docs, authenticated requests, and visible reliability details make it easier to evaluate DomScan before you ship.

Service status API artifacts

OpenAPI, Swagger, Postman, CLI, SDK, and MCP links are one click away.

API keys Protected access

Authenticated endpoints use API keys with clear credit costs before you call them.

Free allowance Sign Up for Free

Start with 10,000 monthly credits and upgrade only when usage grows.

Active Example Request

Start from the curl and HTTP samples, then map the parameters into your application code.

Key Features

Strict Numbering-Plan Validation

Check length and digit patterns against full numbering-plan metadata, not length alone.

Standardized Formats

Return E.164, international, national and RFC 3966 formats, including parsed extensions.

Possible Versus Valid

Separate numbers with a plausible length from ranges recognized by the numbering plan.

Number Type and Prefix Intelligence

Identify number type, numbering-plan location, possible time zones, original prefix carrier, and portability support when metadata has them.

Country-Aware Dialing and Short Codes

Parse national numbers with a country, generate origin-specific dialing formats, and recognize regional short codes and emergency numbers.

Bulk Validation

Validate up to 100 numbers per request with an individual result for every input.

Offline Sources and Official Allocations

Use offline metadata and public regulator snapshots on DomScan infrastructure. Matching results include source, licence, update date, and original allocation context.

Example Request

POST /v1/phone/validate bash

curl -X POST https://domscan.net/v1/phone/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+34 612 345 678","expected_country":"ES","dialing_from_country":"US","language":"en"}'

Example Response

200 OK json

{
  "input": "+34 612 345 678",
  "normalized_input": "+34 612 345 678",
  "kind": "phone_number",
  "valid": true,
  "possible": true,
  "status": "valid",
  "recommendation": "accept",
  "validation_level": "numbering_plan",
  "reason": null,
  "warnings": [],
  "number": {
    "e164": "+34612345678",
    "international": "+34 612 34 56 78",
    "national": "612 34 56 78",
    "rfc3966": "tel:+34612345678",
    "national_number": "612345678",
    "extension": null,
    "country": "ES",
    "country_name": "Spain",
    "country_calling_code": "34",
    "possible_countries": ["ES"],
    "country_match": true,
    "type": "mobile",
    "non_geographic": false
  },
  "intelligence": {
    "status": "available",
    "kind": "phone_number",
    "coverage": {
      "country": "ES",
      "level": "official_allocation_match",
      "global_numbering_metadata": true,
      "official_snapshot_available": true,
      "official_allocation_match": true,
      "official_source_ids": ["cnmc"],
      "matching_source_ids": ["cnmc"],
      "current_carrier_lookup": false
    },
    "location": {
      "country_name": "Spain",
      "country": "ES",
      "granularity": "country",
      "current_physical_location": false
    },
    "possible_time_zones": {
      "values": ["Europe/Madrid"],
      "current_location": false,
      "inference": "number_prefix"
    },
    "original_prefix_carrier": {
      "name": "FOOTBALLERISTA MOBILE SPAIN, S.A. UNIPERSONAL",
      "source_id": "cnmc",
      "evidence": "official_allocation_record",
      "current_carrier": false,
      "portability_may_change_carrier": true
    },
    "portability": {
      "region_supported": true,
      "current_port_checked": false
    },
    "dialing": {
      "from_country": "US",
      "international": "011 34 612 34 56 78",
      "internationally_diallable": true
    },
    "regulator_allocations": [{
      "authority": "CNMC",
      "category": "mobile",
      "status": "assigned",
      "original_assignee": "FOOTBALLERISTA MOBILE SPAIN, S.A. UNIPERSONAL",
      "assigned_on": "2023-11-03",
      "current_operator": false,
      "individual_number_assignment_checked": false
    }],
    "sources": [{
      "id": "google_libphonenumber",
      "name": "Google libphonenumber metadata",
      "license": "Apache-2.0"
    }, {
      "id": "cnmc",
      "name": "Comisión Nacional de los Mercados y la Competencia (CNMC)",
      "type": "official_regulator_snapshot"
    }]
  },
  "live_checks": {
    "assignment": "not_checked",
    "reachability": "not_checked",
    "current_carrier": "not_checked",
    "subscriber_identity": "not_checked",
    "porting": "not_checked"
  },
  "privacy": {
    "upstream_requests": 0,
    "telecom_provider_queried": false,
    "persisted": false,
    "domscan_edge_relay_used": true,
    "third_party_requests": 0
  },
  "limitations": [
    "NUMBERING_PLAN_ONLY",
    "DOES_NOT_PROVE_ASSIGNMENT",
    "NO_LIVE_TELECOM_CHECKS"
  ],
  "credits_used": 1
}

Frequently Asked Questions

What does a valid phone number mean?

Valid means the number matches the documented length and digit patterns of a recognized numbering-plan range. It does not mean the number is assigned to a subscriber.

Does validation prove that the number is active or reachable?

No. Numbering-plan validation cannot confirm that a number is assigned, active, reachable, or able to receive calls or SMS.

Does the API return the current carrier or phone owner?

The API may return an original prefix carrier or regulator allocation holder. Neither field is the current carrier after number porting, and neither identifies the subscriber or phone owner.

Do national phone numbers require a country?

Yes. Provide a default country or region when the number does not start with an international calling code. A country is also required to interpret regional short codes and emergency numbers.

Where does the intelligence data come from?

Global metadata comes from Google libphonenumber. Official range and prefix evidence can also come from public snapshots published by CNMC, ARCEP, Bundesnetzagentur, MIC Japan, RTR Austria, Nkom, UKE Poland, MODA Taiwan, NANPA for the United States, and CNA/CNAC for Canada. US and Canadian records describe NPA-NXX central office code status and original code holders, not the current carrier of a ported number. Each result names its sources, snapshot dates, and coverage level. Location and time zones describe the numbering-plan prefix, not the phone’s current position.

Can I validate phone numbers in bulk?

Yes. The bulk endpoint accepts up to 100 numbers and returns results in input order. If offline enrichment is unavailable, the local validation still completes and intelligence.status reports the fallback.

Related Tools & Resources

HTTP Status Codes

We document the HTTP status codes you should handle so you can distinguish successful responses, auth issues, credits, rate limits, missing data, and upstream failures.

OK 200

Request successful

Bad Request 400

Invalid parameters

Unauthorized 401

Missing or invalid API key/session.

Payment Required 402

Not enough credits to run this request.

Too Many Requests 429

Rate limit exceeded

Server Error 500

Internal error

Bad Gateway 502

Upstream RDAP error

Service Unavailable 503

Upstream service unavailable or temporarily rate limited.

Gateway Timeout 504

Upstream lookup timed out.

Try Phone Number Intelligence for Free

View Full API Documentation APIs

Phone Number Intelligence API

Trust signals before you integrate

What this API helps you ship

Integration workflow

Developer kit

Parameters and response map

Endpoints

Trust signals before you integrate

Key Features

Example Request

Example Response

Frequently Asked Questions

Related Tools & Resources

HTTP Status Codes