> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/zh/docs/products/phone-validation

# 电话号码情报 API 参考

解析、验证、分类和格式化全球电话号码，并在有数据时补充离线的归属地区、时区、号段原始运营商、拨号、短号码和监管机构分配信息。 通过本参考选择合适的端点，并准确了解它返回的内容。

[查看产品页](https://domscan.net/zh/phone-number-validation-api)

## 操作

POST `/v1/phone/validate` [查看 API 参考](https://domscan.net/zh/docs/products/phone-validation#validatePhoneNumber)

POST `/v1/phone/validate/bulk` [查看 API 参考](https://domscan.net/zh/docs/products/phone-validation#validatePhoneNumbersBulk)

## POST `/v1/phone/validate`

操作: `validatePhoneNumber`
积分和身份验证: 1
需要身份验证

POST /v1/phone/validate 积分: 1

#### 正文参数

| 参数 | 类型 | 必需 |
| --- | --- | --- |
| phone | string | 必需 |
| default_country | string | 可选 |
| expected_country | string | 可选 |
| dialing_from_country | string | 可选 |
| language | string | 可选 |

#### 响应字段

| 字段 | 类型 |
| --- | --- |
| `input` | string |
| `normalized_input` | string |
| `kind` | string |
| `valid` | boolean |
| `possible` | boolean |
| `status` | string |
| `recommendation` | string |
| `validation_level` | string |
| `reason` | string \| null |
| `warnings[]` | string[] |
| `number` | object |
| `number.e164` | string |
| `number.international` | string |
| `number.national` | string |
| `number.rfc3966` | string |
| `number.national_number` | string |
| `number.extension` | string \| null |
| `number.country` | string \| null |
| `number.country_name` | string \| null |
| `number.country_calling_code` | string |
| `number.possible_countries[]` | string[] |
| `number.country_match` | boolean \| null |
| `number.type` | string |
| `number.non_geographic` | boolean |
| `live_checks` | object |
| `live_checks.assignment` | string |
| `live_checks.reachability` | string |
| `live_checks.current_carrier` | string |
| `live_checks.subscriber_identity` | string |
| `live_checks.porting` | string |
| `privacy` | object |
| `privacy.upstream_requests` | integer |
| `privacy.telecom_provider_queried` | boolean |
| `privacy.persisted` | boolean |
| `privacy.domscan_edge_relay_used` | boolean |
| `privacy.third_party_requests` | integer |
| `intelligence` | object |
| `intelligence.status` | string |
| `intelligence.kind` | string \| null |
| `intelligence.reason` | string \| null |
| `intelligence.coverage` | object |
| `intelligence.coverage.country` | string \| null |
| `intelligence.coverage.level` | string |
| `intelligence.coverage.global_numbering_metadata` | boolean |
| `intelligence.coverage.official_snapshot_available` | boolean |
| `intelligence.coverage.official_allocation_match` | boolean |
| `intelligence.coverage.official_source_ids[]` | string[] |
| `intelligence.coverage.matching_source_ids[]` | string[] |
| `intelligence.coverage.current_carrier_lookup` | boolean |
| `intelligence.location` | object |
| `intelligence.location.label` | string \| null |
| `intelligence.location.country_name` | string \| null |
| `intelligence.location.country` | string \| null |
| `intelligence.location.language` | string |
| `intelligence.location.granularity` | string |
| `intelligence.location.current_physical_location` | boolean |
| `intelligence.possible_time_zones` | object |
| `intelligence.possible_time_zones.values[]` | string[] |
| `intelligence.possible_time_zones.current_location` | boolean |
| `intelligence.possible_time_zones.inference` | string |
| `intelligence.original_prefix_carrier` | object |
| `intelligence.original_prefix_carrier.name` | string \| null |
| `intelligence.original_prefix_carrier.source_id` | string \| null |
| `intelligence.original_prefix_carrier.evidence` | string |
| `intelligence.original_prefix_carrier.current_carrier` | boolean |
| `intelligence.original_prefix_carrier.portability_may_change_carrier` | boolean |
| `intelligence.portability` | object |
| `intelligence.portability.region_supported` | boolean |
| `intelligence.portability.current_port_checked` | boolean |
| `intelligence.dialing` | object |
| `intelligence.dialing.from_country` | string \| null |
| `intelligence.dialing.international` | string \| null |
| `intelligence.dialing.mobile` | string \| null |
| `intelligence.dialing.internationally_diallable` | boolean |
| `intelligence.number_details` | object |
| `intelligence.number_details.geographical` | boolean |
| `intelligence.number_details.geographical_area_code` | string \| null |
| `intelligence.number_details.geographical_area_code_length` | integer |
| `intelligence.number_details.national_destination_code` | string \| null |
| `intelligence.number_details.national_destination_code_length` | integer |
| `intelligence.number_details.subscriber_number_length` | integer |
| `intelligence.number_details.mobile_token` | string \| null |
| `intelligence.service_signals` | object |
| `intelligence.service_signals.number_type` | string |
| `intelligence.service_signals.geographical` | boolean |
| `intelligence.service_signals.toll_free` | boolean |
| `intelligence.service_signals.premium_rate` | boolean |
| `intelligence.service_signals.shared_cost` | boolean |
| `intelligence.service_signals.voip` | boolean |
| `intelligence.service_signals.personal_number` | boolean |
| `intelligence.service_signals.likely_sms_capable` | boolean \| null |
| `intelligence.short_number` | object |
| `intelligence.short_number.region` | string |
| `intelligence.short_number.possible` | boolean |
| `intelligence.short_number.valid` | boolean |
| `intelligence.short_number.emergency` | boolean |
| `intelligence.short_number.connects_to_emergency` | boolean |
| `intelligence.short_number.sms_service` | boolean |
| `intelligence.short_number.carrier_specific` | boolean |
| `intelligence.short_number.expected_cost` | string |
| `intelligence.regulator_allocations[]` | object[] |
| `intelligence.regulator_allocations[]` | object |
| `intelligence.regulator_allocations[].authority` | string |
| `intelligence.regulator_allocations[].country` | string |
| `intelligence.regulator_allocations[].matched_prefix` | string |
| `intelligence.regulator_allocations[].matched_range_end` | string \| null |
| `intelligence.regulator_allocations[].match_kind` | string |
| `intelligence.regulator_allocations[].category` | string |
| `intelligence.regulator_allocations[].status` | string |
| `intelligence.regulator_allocations[].original_assignee` | string \| null |
| `intelligence.regulator_allocations[].operator_code` | string \| null |
| `intelligence.regulator_allocations[].region` | string \| null |
| `intelligence.regulator_allocations[].service_description` | string \| null |
| `intelligence.regulator_allocations[].assigned_on` | string \| null |
| `intelligence.regulator_allocations[].effective_on` | string \| null |
| `intelligence.regulator_allocations[].expires_on` | string \| null |
| `intelligence.regulator_allocations[].current_operator` | boolean |
| `intelligence.regulator_allocations[].portability_included` | boolean |
| `intelligence.regulator_allocations[].individual_number_assignment_checked` | boolean |
| `intelligence.regulator_allocations[].source_id` | string |
| `intelligence.regulator_allocations[].source_file` | string \| null |
| `intelligence.regulator_allocations[].details` | object |
| `intelligence.sources[]` | object[] |
| `intelligence.sources[]` | object |
| `intelligence.sources[].id` | string |
| `intelligence.sources[].name` | string |
| `intelligence.sources[].type` | string |
| `intelligence.sources[].version` | string \| null |
| `intelligence.sources[].updated_at` | string \| null |
| `intelligence.sources[].retrieved_at` | string \| null |
| `intelligence.sources[].age_days` | integer \| null |
| `intelligence.sources[].record_count` | integer \| null |
| `intelligence.sources[].license` | string \| null |
| `intelligence.sources[].license_url` | string \| null |
| `intelligence.sources[].url` | string |
| `intelligence.sources[].attribution` | string \| null |
| `intelligence.warnings[]` | string[] |
| `intelligence.relay` | object |
| `intelligence.relay.configured` | boolean |
| `intelligence.relay.used` | boolean |
| `intelligence.relay.persisted` | boolean |
| `limitations[]` | string[] |
| `metadata` | object |
| `metadata.engine` | string |
| `metadata.metadata_basis` | string |
| `credits_used` | integer |

#### 请求示例

```bash
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"
}'
```

```javascript
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);
```

```python
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())
```

```go
package main

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")

```ruby
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"
})

#### 响应示例

```json
{
  "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 状态码

- `200` 成功
- `400` 请求错误
- `401` 未授权
- `402` 需要付款
- `409` HTTP 409
- `422` HTTP 422
- `429` 请求过多
- `500` 服务器错误

## POST `/v1/phone/validate/bulk`

操作: `validatePhoneNumbersBulk`
积分和身份验证: 1
需要身份验证

POST /v1/phone/validate/bulk 积分: 1/item

#### 查询参数

| 参数 | 类型 | 必需 |
| --- | --- | --- |
| dry_run | string 允许的值 `true` | 可选 |

#### 正文参数

| 参数 | 类型 | 必需 |
| --- | --- | --- |
| phones | unknown[] | 必需 |
| default_country | string | 可选 |
| expected_country | string | 可选 |
| dialing_from_country | string | 可选 |
| language | string | 可选 |

#### 响应字段

| 字段 | 类型 |
| --- | --- |
| `total` | integer |
| `valid_count` | integer |
| `possible_only_count` | integer |
| `invalid_count` | integer |
| `validation_level` | string |
| `results[]` | object[] |
| `results[]` | object |
| `results[].input` | string |
| `results[].normalized_input` | string |
| `results[].kind` | string |
| `results[].valid` | boolean |
| `results[].possible` | boolean |
| `results[].status` | string |
| `results[].recommendation` | string |
| `results[].validation_level` | string |
| `results[].reason` | string \| null |
| `results[].warnings[]` | string[] |
| `results[].number` | object |
| `results[].number.e164` | string |
| `results[].number.international` | string |
| `results[].number.national` | string |
| `results[].number.rfc3966` | string |
| `results[].number.national_number` | string |
| `results[].number.extension` | string \| null |
| `results[].number.country` | string \| null |
| `results[].number.country_name` | string \| null |
| `results[].number.country_calling_code` | string |
| `results[].number.possible_countries[]` | string[] |
| `results[].number.country_match` | boolean \| null |
| `results[].number.type` | string |
| `results[].number.non_geographic` | boolean |
| `results[].live_checks` | object |
| `results[].live_checks.assignment` | string |
| `results[].live_checks.reachability` | string |
| `results[].live_checks.current_carrier` | string |
| `results[].live_checks.subscriber_identity` | string |
| `results[].live_checks.porting` | string |
| `results[].privacy` | object |
| `results[].privacy.upstream_requests` | integer |
| `results[].privacy.telecom_provider_queried` | boolean |
| `results[].privacy.persisted` | boolean |
| `results[].privacy.domscan_edge_relay_used` | boolean |
| `results[].privacy.third_party_requests` | integer |
| `results[].intelligence` | object |
| `results[].intelligence.status` | string |
| `results[].intelligence.kind` | string \| null |
| `results[].intelligence.reason` | string \| null |
| `results[].intelligence.coverage` | object |
| `results[].intelligence.coverage.country` | string \| null |
| `results[].intelligence.coverage.level` | string |
| `results[].intelligence.coverage.global_numbering_metadata` | boolean |
| `results[].intelligence.coverage.official_snapshot_available` | boolean |
| `results[].intelligence.coverage.official_allocation_match` | boolean |
| `results[].intelligence.coverage.official_source_ids[]` | string[] |
| `results[].intelligence.coverage.matching_source_ids[]` | string[] |
| `results[].intelligence.coverage.current_carrier_lookup` | boolean |
| `results[].intelligence.location` | object |
| `results[].intelligence.location.label` | string \| null |
| `results[].intelligence.location.country_name` | string \| null |
| `results[].intelligence.location.country` | string \| null |
| `results[].intelligence.location.language` | string |
| `results[].intelligence.location.granularity` | string |
| `results[].intelligence.location.current_physical_location` | boolean |
| `results[].intelligence.possible_time_zones` | object |
| `results[].intelligence.possible_time_zones.values[]` | string[] |
| `results[].intelligence.possible_time_zones.current_location` | boolean |
| `results[].intelligence.possible_time_zones.inference` | string |
| `results[].intelligence.original_prefix_carrier` | object |
| `results[].intelligence.original_prefix_carrier.name` | string \| null |
| `results[].intelligence.original_prefix_carrier.source_id` | string \| null |
| `results[].intelligence.original_prefix_carrier.evidence` | string |
| `results[].intelligence.original_prefix_carrier.current_carrier` | boolean |
| `results[].intelligence.original_prefix_carrier.portability_may_change_carrier` | boolean |
| `results[].intelligence.portability` | object |
| `results[].intelligence.portability.region_supported` | boolean |
| `results[].intelligence.portability.current_port_checked` | boolean |
| `results[].intelligence.dialing` | object |
| `results[].intelligence.dialing.from_country` | string \| null |
| `results[].intelligence.dialing.international` | string \| null |
| `results[].intelligence.dialing.mobile` | string \| null |
| `results[].intelligence.dialing.internationally_diallable` | boolean |
| `results[].intelligence.number_details` | object |
| `results[].intelligence.number_details.geographical` | boolean |
| `results[].intelligence.number_details.geographical_area_code` | string \| null |
| `results[].intelligence.number_details.geographical_area_code_length` | integer |
| `results[].intelligence.number_details.national_destination_code` | string \| null |
| `results[].intelligence.number_details.national_destination_code_length` | integer |
| `results[].intelligence.number_details.subscriber_number_length` | integer |
| `results[].intelligence.number_details.mobile_token` | string \| null |
| `results[].intelligence.service_signals` | object |
| `results[].intelligence.service_signals.number_type` | string |
| `results[].intelligence.service_signals.geographical` | boolean |
| `results[].intelligence.service_signals.toll_free` | boolean |
| `results[].intelligence.service_signals.premium_rate` | boolean |
| `results[].intelligence.service_signals.shared_cost` | boolean |
| `results[].intelligence.service_signals.voip` | boolean |
| `results[].intelligence.service_signals.personal_number` | boolean |
| `results[].intelligence.service_signals.likely_sms_capable` | boolean \| null |
| `results[].intelligence.short_number` | object |
| `results[].intelligence.short_number.region` | string |
| `results[].intelligence.short_number.possible` | boolean |
| `results[].intelligence.short_number.valid` | boolean |
| `results[].intelligence.short_number.emergency` | boolean |
| `results[].intelligence.short_number.connects_to_emergency` | boolean |
| `results[].intelligence.short_number.sms_service` | boolean |
| `results[].intelligence.short_number.carrier_specific` | boolean |
| `results[].intelligence.short_number.expected_cost` | string |
| `results[].intelligence.regulator_allocations[]` | object[] |
| `results[].intelligence.regulator_allocations[]` | object |
| `results[].intelligence.regulator_allocations[].authority` | string |
| `results[].intelligence.regulator_allocations[].country` | string |
| `results[].intelligence.regulator_allocations[].matched_prefix` | string |
| `results[].intelligence.regulator_allocations[].matched_range_end` | string \| null |
| `results[].intelligence.regulator_allocations[].match_kind` | string |
| `results[].intelligence.regulator_allocations[].category` | string |
| `results[].intelligence.regulator_allocations[].status` | string |
| `results[].intelligence.regulator_allocations[].original_assignee` | string \| null |
| `results[].intelligence.regulator_allocations[].operator_code` | string \| null |
| `results[].intelligence.regulator_allocations[].region` | string \| null |
| `results[].intelligence.regulator_allocations[].service_description` | string \| null |
| `results[].intelligence.regulator_allocations[].assigned_on` | string \| null |
| `results[].intelligence.regulator_allocations[].effective_on` | string \| null |
| `results[].intelligence.regulator_allocations[].expires_on` | string \| null |
| `results[].intelligence.regulator_allocations[].current_operator` | boolean |
| `results[].intelligence.regulator_allocations[].portability_included` | boolean |
| `results[].intelligence.regulator_allocations[].individual_number_assignment_checked` | boolean |
| `results[].intelligence.regulator_allocations[].source_id` | string |
| `results[].intelligence.regulator_allocations[].source_file` | string \| null |
| `results[].intelligence.regulator_allocations[].details` | object |
| `results[].intelligence.sources[]` | object[] |
| `results[].intelligence.sources[]` | object |
| `results[].intelligence.sources[].id` | string |
| `results[].intelligence.sources[].name` | string |
| `results[].intelligence.sources[].type` | string |
| `results[].intelligence.sources[].version` | string \| null |
| `results[].intelligence.sources[].updated_at` | string \| null |
| `results[].intelligence.sources[].retrieved_at` | string \| null |
| `results[].intelligence.sources[].age_days` | integer \| null |
| `results[].intelligence.sources[].record_count` | integer \| null |
| `results[].intelligence.sources[].license` | string \| null |
| `results[].intelligence.sources[].license_url` | string \| null |
| `results[].intelligence.sources[].url` | string |
| `results[].intelligence.sources[].attribution` | string \| null |
| `results[].intelligence.warnings[]` | string[] |
| `results[].intelligence.relay` | object |
| `results[].intelligence.relay.configured` | boolean |
| `results[].intelligence.relay.used` | boolean |
| `results[].intelligence.relay.persisted` | boolean |
| `results[].limitations[]` | string[] |
| `results[].metadata` | object |
| `results[].metadata.engine` | string |
| `results[].metadata.metadata_basis` | string |
| `credits_used` | integer |

#### 请求示例

```bash
curl -X POST "https://domscan.net/v1/phone/validate/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "expected_country": "ES",
  "dialing_from_country": "US",
  "language": "en",
  "phones": [
    "+34 612 345 678",
    {
      "phone": "0491 570 006",
      "default_country": "AU",
      "expected_country": "AU",
      "dialing_from_country": "GB",
      "language": "en"
    },
    "+800 1234 5678"
  ]
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/phone/validate/bulk", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "expected_country": "ES",
    "dialing_from_country": "US",
    "language": "en",
    "phones": [
      "+34 612 345 678",
      {
        "phone": "0491 570 006",
        "default_country": "AU",
        "expected_country": "AU",
        "dialing_from_country": "GB",
        "language": "en"
      },
      "+800 1234 5678"
    ]
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/phone/validate/bulk",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "expected_country": "ES",
        "dialing_from_country": "US",
        "language": "en",
        "phones": [
            "+34 612 345 678",
            {
                "phone": "0491 570 006",
                "default_country": "AU",
                "expected_country": "AU",
                "dialing_from_country": "GB",
                "language": "en",
            },
            "+800 1234 5678",
        ],
    },
)
print(response.json())
```

```go
package main

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

func main() {
	body := strings.NewReader(`{
	  "expected_country": "ES",
	  "dialing_from_country": "US",
	  "language": "en",
	  "phones": [
	    "+34 612 345 678",
	    {
	      "phone": "0491 570 006",
	      "default_country": "AU",
	      "expected_country": "AU",
	      "dialing_from_country": "GB",
	      "language": "en"
	    },
	    "+800 1234 5678"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/phone/validate/bulk", 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))
}
```

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/phone/validate/bulk")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "expected_country" => "ES",
  "dialing_from_country" => "US",
  "language" => "en",
  "phones" => [
    "+34 612 345 678",
    {
      "phone" => "0491 570 006",
      "default_country" => "AU",
      "expected_country" => "AU",
      "dialing_from_country" => "GB",
      "language" => "en"
    },
    "+800 1234 5678"
  ]
})

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))
```

#### 响应示例

```json
{
  "total": 1,
  "valid_count": 1,
  "possible_only_count": 1,
  "invalid_count": 1,
  "validation_level": "numbering_plan",
  "results": [
    {
      "input": "example",
      "normalized_input": "example",
      "kind": "phone_number",
      "valid": true,
      "possible": false,
      "status": "valid",
      "recommendation": "accept",
      "validation_level": "numbering_plan",
      "reason": "DEFAULT_COUNTRY_REQUIRED",
      "warnings": [
        "COUNTRY_MISMATCH"
      ],
      "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": false,
        "type": "fixed_line",
        "non_geographic": false
      },
      "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": false,
        "third_party_requests": 0
      },
      "intelligence": {
        "status": "available",
        "kind": "phone_number",
        "reason": "example",
        "coverage": {
          "country": "US",
          "level": "global_numbering_metadata",
          "global_numbering_metadata": false,
          "official_snapshot_available": true,
          "official_allocation_match": false,
          "official_source_ids": [
            "example"
          ],
          "matching_source_ids": [
            "example"
          ],
          "current_carrier_lookup": false
        },
        "location": {
          "label": "Madrid",
          "country_name": "Spain",
          "country": "ES",
          "language": "es",
          "granularity": "numbering_plan_area",
          "current_physical_location": false
        },
        "possible_time_zones": {
          "values": [
            "Europe/Madrid"
          ],
          "current_location": false,
          "inference": "number_prefix"
        },
        "original_prefix_carrier": {
          "name": "Vodafone",
          "source_id": "nanpa_us",
          "evidence": "offline_prefix_metadata",
          "current_carrier": false,
          "portability_may_change_carrier": false
        },
        "portability": {
          "region_supported": false,
          "current_port_checked": false
        },
        "dialing": {
          "from_country": "US",
          "international": "011 34 612 34 56 78",
          "mobile": "+34 612 34 56 78",
          "internationally_diallable": false
        },
        "number_details": {
          "geographical": false,
          "geographical_area_code": "example",
          "geographical_area_code_length": 1,
          "national_destination_code": "example",
          "national_destination_code_length": 1,
          "subscriber_number_length": 1,
          "mobile_token": "example"
        },
        "service_signals": {
          "number_type": "fixed_line",
          "geographical": false,
          "toll_free": false,
          "premium_rate": false,
          "shared_cost": false,
          "voip": false,
          "personal_number": false,
          "likely_sms_capable": false
        },
        "short_number": {
          "region": "ES",
          "possible": false,
          "valid": true,
          "emergency": false,
          "connects_to_emergency": false,
          "sms_service": false,
          "carrier_specific": false,
          "expected_cost": "toll_free"
        },
        "regulator_allocations": [
          {
            "authority": "CNMC",
            "country": "ES",
            "matched_prefix": "912",
            "matched_range_end": "example",
            "match_kind": "prefix",
            "category": "geographic",
            "status": "assigned",
            "original_assignee": "Example Telecom",
            "operator_code": "example",
            "region": "Madrid",
            "service_description": "example",
            "assigned_on": "2026-08-27",
            "effective_on": "2026-08-27",
            "expires_on": "2026-08-27",
            "current_operator": false,
            "portability_included": false,
            "individual_number_assignment_checked": false,
            "source_id": "cnmc",
            "source_file": "example",
            "details": {}
          }
        ],
        "sources": [
          {
            "id": "google_libphonenumber",
            "name": "Google libphonenumber metadata",
            "type": "offline_metadata",
            "url": "https://example.com",
            "version": "9.0.34",
            "updated_at": "2026-08-27T12:00:00Z",
            "retrieved_at": "2026-08-27T12:00:00Z",
            "age_days": 1,
            "record_count": 1,
            "license": "Apache-2.0",
            "license_url": "https://example.com",
            "attribution": "example"
          }
        ],
        "warnings": [
          "example"
        ],
        "relay": {
          "configured": false,
          "used": false,
          "persisted": false
        }
      },
      "limitations": [
        "example"
      ],
      "metadata": {
        "engine": "libphonenumber-js/max",
        "metadata_basis": "Google libphonenumber numbering plans"
      }
    }
  ],
  "credits_used": 1
}
```

#### HTTP 状态码

- `200` 成功
- `400` 请求错误
- `401` 未授权
- `402` 需要付款
- `409` HTTP 409
- `422` HTTP 422
- `429` 请求过多
- `500` 服务器错误

## 参考资源

[OpenAPI 3.0](https://domscan.net/v1/openapi.json)
[Postman](https://domscan.net/v1/postman.json)
[MCP](https://domscan.net/zh/mcp-domain-checker)
