Phone Number Intelligence API

Example request

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

const response = await fetch("https://domscan.net/v1/phone/validate", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "phone": "+34 612 345 678",
    "default_country": "ES",
    "expected_country": "ES",
    "dialing_from_country": "ES",
    "language": "es"
  }),
});
const data = await response.json();
console.log(data);

import os
import requests

response = requests.post(
    "https://domscan.net/v1/phone/validate",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "phone": "+34 612 345 678",
        "default_country": "ES",
        "expected_country": "ES",
        "dialing_from_country": "ES",
        "language": "es",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "phone": "+34 612 345 678",
	  "default_country": "ES",
	  "expected_country": "ES",
	  "dialing_from_country": "ES",
	  "language": "es"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/phone/validate", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}

require "json"
require "net/http"

uri = URI("https://domscan.net/v1/phone/validate")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "phone" => "+34 612 345 678",
  "default_country" => "ES",
  "expected_country" => "ES",
  "dialing_from_country" => "ES",
  "language" => "es"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))

Example response

{
  "input": "+44 20 7946 0123",
  "normalized_input": "+44 20 7946 0123",
  "validation_level": "numbering_plan",
  "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
  },
  "intelligence": {
    "status": "available",
    "kind": "phone_number",
    "reason": null,
    "coverage": {
      "country": "GB",
      "level": "global_numbering_metadata",
      "global_numbering_metadata": true,
      "official_snapshot_available": false,
      "official_allocation_match": false,
      "official_source_ids": [],
      "matching_source_ids": [],
      "current_carrier_lookup": false
    },
    "location": {
      "label": "London",
      "country_name": "United Kingdom",
      "country": "GB",
      "language": "en",
      "granularity": "numbering_plan_area",
      "current_physical_location": false
    },
    "possible_time_zones": {
      "values": [
        "Europe/London"
      ],
      "current_location": false,
      "inference": "number_prefix"
    },
    "original_prefix_carrier": {
      "name": null,
      "source_id": null,
      "evidence": "unavailable",
      "current_carrier": false,
      "portability_may_change_carrier": true
    },
    "portability": {
      "region_supported": true,
      "current_port_checked": false
    },
    "dialing": {
      "from_country": "US",
      "international": "011 44 20 7946 0123",
      "mobile": "+44 20 7946 0123",
      "internationally_diallable": true
    },
    "number_details": {
      "geographical": true,
      "geographical_area_code": "20",
      "geographical_area_code_length": 2,
      "national_destination_code": "20",
      "national_destination_code_length": 2,
      "subscriber_number_length": 8,
      "mobile_token": null
    },
    "service_signals": {
      "number_type": "fixed_line",
      "geographical": true,
      "toll_free": false,
      "premium_rate": false,
      "shared_cost": false,
      "voip": false,
      "personal_number": false,
      "likely_sms_capable": null
    },
    "short_number": null,
    "regulator_allocations": [],
    "sources": [
      {
        "id": "google_libphonenumber",
        "name": "Google libphonenumber metadata",
        "type": "offline_metadata",
        "version": "9.0.34",
        "license": "Apache-2.0",
        "url": "https://github.com/google/libphonenumber"
      }
    ],
    "warnings": [
      "LOCATION_IS_NUMBERING_PLAN_AREA_NOT_DEVICE_LOCATION",
      "CARRIER_IS_ORIGINAL_PREFIX_CARRIER_NOT_CURRENT_CARRIER",
      "ALLOCATION_DOES_NOT_PROVE_INDIVIDUAL_ASSIGNMENT",
      "NO_CURRENT_PORTABILITY_LOOKUP",
      "NO_LIVE_TELECOM_CHECKS"
    ],
    "relay": {
      "configured": true,
      "used": true,
      "persisted": false
    }
  },
  "limitations": [
    "NUMBERING_PLAN_ONLY",
    "DOES_NOT_PROVE_ASSIGNMENT",
    "NO_LIVE_TELECOM_CHECKS"
  ],
  "metadata": {
    "engine": "libphonenumber-js/max",
    "metadata_basis": "Google libphonenumber numbering plans"
  },
  "kind": "phone_number",
  "valid": true,
  "possible": true,
  "status": "valid",
  "recommendation": "accept",
  "reason": null,
  "warnings": [],
  "number": {
    "e164": "+442079460123",
    "international": "+44 20 7946 0123",
    "national": "020 7946 0123",
    "rfc3966": "tel:+442079460123",
    "national_number": "2079460123",
    "extension": null,
    "country": "GB",
    "country_name": "United Kingdom",
    "country_calling_code": "44",
    "possible_countries": [
      "GB"
    ],
    "country_match": true,
    "type": "fixed_line",
    "non_geographic": false
  },
  "credits_used": 1
}

HTTP status codes

• 200 OK
• 400 Bad Request
• 401 Unauthorized
• 402 Payment Required
• 409 HTTP 409
• 422 HTTP 422
• 429 Too Many Requests
• 500 Server Error