API reference / Introduction
Phone data.
Ready to build with.
Look up calling codes, normalize phone numbers, and prepare international calls. One public API for your app and your AI agents.
Send JSON over HTTPS. Receive structured results with explicit uncertainty and versioned evidence. No API key is required.
Numbering metadata describes valid formats. It does not establish that a number is active, reachable, owned by someone, or safe to contact.
https://www.countrycalling.codescurl 'https://www.countrycalling.codes/api/phone/analyze' \
-H 'Content-Type: application/json' \
--data '{
"phoneNumber": "(020) 7946 0123",
"numberCountryCode": "GB"
}'Examples use synthetic numbers. Code snippets make real requests when you run them.
Authentication & requests
REST and MCP are public and read-only. There is no API key, OAuth flow, or per-request API fee charged by this service. Use the HTTPS base URL above.
For POST workflows, send uncompressed application/json. Country context is a two-letter ISO code. National numbers need numberCountryCode; exit prefixes need originCountryCode. These fields answer different questions.
Cross-origin requests are supported. Phone-bearing responses use Cache-Control: no-store. Do not put phone numbers in URLs or application logs. MCP clients and gateways may retain conversation history.
Read X-API-Version on REST responses. Workflow envelopes also identify the dataset and numbering metadata versions. Version headers report the running version; they do not select historical versions.
All operations are read-only. A retry does not create records or place a call. Retry transient 5xx responses with bounded backoff; honor Retry-After on 429 when supplied.
Content-Type: application/json
Accept: application/jsonUse a national number’s country as context. Never assume the caller’s country is the number’s country.
Errors & domain outcomes
An HTTP 200 means the request was processed. Analysis can still return needs-context, ambiguous, unsupported, or invalid. Inspect the result before using the number.
| Status | What to do |
|---|---|
200 | Inspect the result and its limitations; batch records may contain individual errors. |
304 | Public metadata is unchanged. Reuse your cached representation. |
400 | Fix the request fields, JSON, or duplicate query parameters. |
404 | The direct country lookup found no match. |
413 | Reduce the request body. |
415 | Send uncompressed application/json. |
429 | A hosting limit may apply. Back off; honor Retry-After when present. |
500 | Retry with bounded backoff or contact support if persistent. |
{
"error": {
"code": "INVALID_REQUEST",
"message": "Check the documented request schema and limits.",
"details": [
{
"field": "phoneNumber",
"message": "Invalid field."
}
]
},
"documentation": "https://www.countrycalling.codes/developers#enhanced-api"
}Malformed bodies and media-type failures may omit field details. Each endpoint’s response schema is documented below.
Limits & coverage
Number analysis uses libphonenumber-js 1.13.12 metadata for 245 countries and territories. Editorially reviewed guides cover US, GB, DE, FR, IN, CN, JP, AU, BR, ZA, SG, AE, IT, HK, ES, TR, MX, MY, ID, UA. Check capabilities before relying on a particular workflow.
| Resource | Limit / behavior |
|---|---|
| Workflow REST bodies | 64 KiB; phone strings up to 64 characters. |
| MCP | 128 KiB transport envelope; enhanced tool arguments limited to 64 KiB. |
| Batch normalization | 1–100 records; unique record IDs; individual validation errors. |
| Calling windows | 1–8 participants, 1–31 inclusive days, 1–20 returned windows. Explicit IANA zones. |
| Scheduling policy | One-minute precision. Nonexistent DST minutes are skipped; repeated minutes are both eligible. Holidays are not excluded. |
| Request quota | No application-level per-client quota is configured. Hosting limits can still apply. |
| Metadata caching | Capabilities and input rules support ETags. Phone results are not cached. |
Phone capabilities
GET
/api/capabilitiesDiscover supported countries, per-operation review coverage, evidence, dataset versions and request limits before choosing a phone workflow.
MCP tool: get_phone_capabilities
Path & query parameters
countryCodestringoptional- Two-letter ISO country code, for example GB.
- Pattern: ^[a-zA-Z]{2}$
operationstringoptional- Values: get_phone_capabilities, analyze_phone_number, get_dialing_instructions, normalize_phone_numbers, compare_phone_numbers, resolve_phone_region, get_phone_input_rules, diagnose_dialing_problem, find_calling_windows
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
304 | Metadata unchanged (If-None-Match). |
400 | Invalid request or duplicate parameters. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/capabilities?countryCode=GB'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
operationsarrayrequiredlimitsobjectrequiredShow child fields
bodyBytesnumberrequiredbatchItemsnumberrequiredphoneCharactersnumberrequiredschedulingDaysnumberrequiredschedulingParticipantsnumberrequiredrateLimitstringrequired
countriesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredcallingCodestring | nullrequiredsupportedOperationsarrayrequiredreviewStatusstringrequired- Values: reviewed-guide-and-metadata, numbering-metadata, directory-only
lastVerifiedstring | nullrequiredevidenceIdsarrayrequiredsourceUrlsarrayrequiredlimitationsarrayrequired
evidencearrayrequiredShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"operations": {
"type": "array",
"items": {
"type": "string",
"enum": [
"get_phone_capabilities",
"analyze_phone_number",
"get_dialing_instructions",
"normalize_phone_numbers",
"compare_phone_numbers",
"resolve_phone_region",
"get_phone_input_rules",
"diagnose_dialing_problem",
"find_calling_windows"
]
}
},
"limits": {
"type": "object",
"properties": {
"bodyBytes": {
"type": "number"
},
"batchItems": {
"type": "number"
},
"phoneCharacters": {
"type": "number"
},
"schedulingDays": {
"type": "number"
},
"schedulingParticipants": {
"type": "number"
},
"rateLimit": {
"type": "string"
}
},
"required": [
"bodyBytes",
"batchItems",
"phoneCharacters",
"schedulingDays",
"schedulingParticipants",
"rateLimit"
],
"additionalProperties": false
},
"countries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"callingCode": {
"type": [
"string",
"null"
]
},
"supportedOperations": {
"type": "array",
"items": {
"type": "string"
}
},
"reviewStatus": {
"type": "string",
"enum": [
"reviewed-guide-and-metadata",
"numbering-metadata",
"directory-only"
]
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"sourceUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"countryCode",
"name",
"callingCode",
"supportedOperations",
"reviewStatus",
"lastVerified",
"evidenceIds",
"sourceUrls",
"limitations"
],
"additionalProperties": false
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"operations",
"limits",
"countries",
"evidence"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: get_phone_capabilities
Analyze phone number
POST
/api/phone/analyzeAnalyze a number using versioned numbering metadata. National numbers need numberCountryCode; exit prefixes need originCountryCode. Reports uncertainty and rule evidence, never live subscriber status.
MCP tool: analyze_phone_number
Body parameters
phoneNumberstringrequired- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
numberCountryCodestringoptional- Two-letter ISO country code for national input, such as GB. This identifies the numbering plan, not where the call starts.
- Pattern: ^[a-zA-Z]{2}$
originCountryCodestringoptional- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/phone/analyze' \
-H 'Content-Type: application/json' \
--data '{
"phoneNumber": "(020) 7946 0123",
"numberCountryCode": "GB",
"detail": "full"
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: analyze_phone_number
Dialing instructions
POST
/api/dialing/instructionsPrepare origin-specific dialing guidance for reviewed countries. Provide origin and destination separately; no phone number returns safe placeholder patterns. Network-dependent results remain conditional.
MCP tool: get_dialing_instructions
Body parameters
originCountryCodestringrequired- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
destinationCountryCodestringrequired- Two-letter ISO destination country for reviewed dialing guidance.
- Pattern: ^[a-zA-Z]{2}$
phoneNumberstringoptional- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
devicestringoptional- The dialing device; unknown leaves device-dependent guidance conditional.
- Values: mobile, landline, unknown · Default: "unknown"
carrierSelectionCodestringoptional- Optional two-digit carrier selection code for supported origin rules.
- Pattern: ^[0-9]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/dialing/instructions' \
-H 'Content-Type: application/json' \
--data '{
"originCountryCode": "US",
"destinationCountryCode": "GB",
"phoneNumber": "+442079460123",
"device": "landline"
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
statusstringrequired- Values: ready, guidance, needs-context, unsupported, invalid, ambiguous
routestringrequired- Values: domestic, international, shared-plan
canonicalInternationalstring | nullrequiredrecommendedDisplaystring | nullrequireddialStringstring | nullrequiredpatternstring | nullrequiredstepsarrayrequiredShow item fields
labelstringrequiredvaluestringrequired
extensionInstructionsstring | nullrequiredreasonCodesarrayrequiredrequiredContextarrayrequirednotesarrayrequiredevidencearrayrequiredShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"guidance",
"needs-context",
"unsupported",
"invalid",
"ambiguous"
]
},
"route": {
"type": "string",
"enum": [
"domestic",
"international",
"shared-plan"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"recommendedDisplay": {
"type": [
"string",
"null"
]
},
"dialString": {
"type": [
"string",
"null"
]
},
"pattern": {
"type": [
"string",
"null"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"label",
"value"
],
"additionalProperties": false
}
},
"extensionInstructions": {
"type": [
"string",
"null"
]
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"route",
"canonicalInternational",
"recommendedDisplay",
"dialString",
"pattern",
"steps",
"extensionInstructions",
"reasonCodes",
"requiredContext",
"notes",
"evidence"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: get_dialing_instructions
Normalize phone batch
POST
/api/phone/batchNormalize up to 100 records with unique IDs. Invalid records produce individual errors. Optionally identify canonical duplicate candidates; no contacts are changed or stored.
MCP tool: normalize_phone_numbers
Body parameters
itemsarrayrequired- 1–100 records with unique IDs. Invalid record contents produce individual errors; duplicate IDs reject the request.
- Min items: 1 · Max items: 100
Show item fields
idstringrequired- Min characters: 1 · Max characters: 64
phoneNumberanyoptional- For a successful record, provide a non-empty phone string up to 64 characters. Malformed values return a per-record error.
numberCountryCodeanyoptional- Optional two-letter ISO country context for this number.
originCountryCodeanyoptional- Optional two-letter ISO origin for interpreting an exit prefix.
detailanyoptional- compact (default) or full to expand source evidence.
findDuplicatesbooleanoptional- Include groups of canonical duplicate candidates. The API does not change or store contacts.
- Default: false
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/phone/batch' \
-H 'Content-Type: application/json' \
--data '{
"items": [
{
"id": "a",
"phoneNumber": "020 7946 0123",
"numberCountryCode": "GB"
},
{
"id": "b",
"phoneNumber": "+442079460123"
},
{
"id": "c",
"phoneNumber": "5550100"
}
],
"findDuplicates": true
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
itemsarrayrequired- 1–100 records with unique IDs. Invalid record contents produce individual errors; duplicate IDs reject the request.
Show item fields
idstringrequiredresultobjectoptionalShow child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
errorobjectoptionalShow child fields
codestringrequiredmessagestringrequiredfieldsarrayoptional
countsobjectrequiredShow child fields
totalnumberrequiredanalyzednumberrequiredambiguousnumberrequiredneedsContextnumberrequiredunsupportednumberrequiredinvalidnumberrequirederrorsnumberrequired
duplicateGroupsarrayrequiredShow item fields
itemIdsarrayrequiredextensionsDifferbooleanrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id"
],
"additionalProperties": false
}
},
"counts": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"analyzed": {
"type": "number"
},
"ambiguous": {
"type": "number"
},
"needsContext": {
"type": "number"
},
"unsupported": {
"type": "number"
},
"invalid": {
"type": "number"
},
"errors": {
"type": "number"
}
},
"required": [
"total",
"analyzed",
"ambiguous",
"needsContext",
"unsupported",
"invalid",
"errors"
],
"additionalProperties": false
},
"duplicateGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"itemIds": {
"type": "array",
"items": {
"type": "string"
}
},
"extensionsDiffer": {
"type": "boolean"
}
},
"required": [
"itemIds",
"extensionsDiffer"
],
"additionalProperties": false
}
}
},
"required": [
"items",
"counts",
"duplicateGroups"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: normalize_phone_numbers
Compare phone numbers
POST
/api/phone/compareCompare two numbers after analysis. Missing context produces indeterminate. Extensions must match unless extensionPolicy is explicitly ignore; equality does not establish ownership.
MCP tool: compare_phone_numbers
Body parameters
leftobjectrequired- First number and its own country context.
Show child fields
phoneNumberstringrequired- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
numberCountryCodestringoptional- Two-letter ISO country code for national input, such as GB. This identifies the numbering plan, not where the call starts.
- Pattern: ^[a-zA-Z]{2}$
originCountryCodestringoptional- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
rightobjectrequired- Second number and its own country context.
Show child fields
phoneNumberstringrequired- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
numberCountryCodestringoptional- Two-letter ISO country code for national input, such as GB. This identifies the numbering plan, not where the call starts.
- Pattern: ^[a-zA-Z]{2}$
originCountryCodestringoptional- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
extensionPolicystringoptional- exact requires matching extensions. ignore compares the base numbers only.
- Values: exact, ignore · Default: "exact"
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/phone/compare' \
-H 'Content-Type: application/json' \
--data '{
"left": {
"phoneNumber": "020 7946 0123",
"numberCountryCode": "GB"
},
"right": {
"phoneNumber": "+442079460123"
},
"extensionPolicy": "exact"
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
matchstringrequired- Values: same, different, indeterminate
baseNumberMatchboolean | nullrequiredextensionMatchboolean | nullrequiredreasonCodesarrayrequiredleftobjectrequired- First number and its own country context.
Show child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
rightobjectrequired- Second number and its own country context.
Show child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"match": {
"type": "string",
"enum": [
"same",
"different",
"indeterminate"
]
},
"baseNumberMatch": {
"type": [
"boolean",
"null"
]
},
"extensionMatch": {
"type": [
"boolean",
"null"
]
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"left": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
},
"right": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
}
},
"required": [
"match",
"baseNumberMatch",
"extensionMatch",
"reasonCodes",
"left",
"right"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: compare_phone_numbers
Resolve phone region
POST
/api/phone/regionResolve a phone number to metadata-backed country candidates or non-geographic numbering. Results are numbering assignments, not current location or carrier.
MCP tool: resolve_phone_region
Body parameters
phoneNumberstringrequired- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
numberCountryCodestringoptional- Two-letter ISO country code for national input, such as GB. This identifies the numbering plan, not where the call starts.
- Pattern: ^[a-zA-Z]{2}$
originCountryCodestringoptional- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/phone/region' \
-H 'Content-Type: application/json' \
--data '{
"phoneNumber": "+442079460123"
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
analysisobjectrequiredShow child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
metadataEvidenceobjectrequiredShow child fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
resolutionstringrequired- Values: resolved, ambiguous, non-geographic, unresolved
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"analysis": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
},
"metadataEvidence": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
},
"resolution": {
"type": "string",
"enum": [
"resolved",
"ambiguous",
"non-geographic",
"unresolved"
]
}
},
"required": [
"analysis",
"metadataEvidence",
"resolution"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: resolve_phone_region
Phone input guidance
GET
/api/countries/{code}/phone-inputGet reviewed display placeholders and trunk-prefix guidance. Examples are not validation masks. English fallback and unsupported editorial coverage are explicit.
MCP tool: get_phone_input_rules
Path & query parameters
codestringrequired- Pattern: ^[a-zA-Z]{2}$
localestringoptional- Requested locale. The response explicitly reports English fallback when needed.
- Default: "en" · Min characters: 2 · Max characters: 35
Substitute path parameters in the URL. All remaining parameters are query parameters.
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
304 | Metadata unchanged (If-None-Match). |
400 | Invalid request or duplicate parameters. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/countries/GB/phone-input?locale=en'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
statusstringrequired- Values: supported, unsupported
countryCodestringrequired- Two-letter ISO country code, for example GB.
localestringrequired- Requested locale. The response explicitly reports English fallback when needed.
requestedLocalestringrequiredfallbackbooleanrequiredcallingCodestring | nullrequirednationalLengthsunionrequiredShow alternatives
[ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ]patternsarrayrequiredShow item fields
kindstringrequirednationalstringrequiredinternationalstringrequired
trunkPrefixRulestring | nullrequiredextensionSupportedbooleanrequiredhintsarrayrequiredevidencearrayrequiredShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"supported",
"unsupported"
]
},
"countryCode": {
"type": "string"
},
"locale": {
"type": "string"
},
"requestedLocale": {
"type": "string"
},
"fallback": {
"type": "boolean"
},
"callingCode": {
"type": [
"string",
"null"
]
},
"nationalLengths": {
"anyOf": [
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "null"
}
]
},
"patterns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"national": {
"type": "string"
},
"international": {
"type": "string"
}
},
"required": [
"kind",
"national",
"international"
],
"additionalProperties": false
}
},
"trunkPrefixRule": {
"type": [
"string",
"null"
]
},
"extensionSupported": {
"type": "boolean"
},
"hints": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"countryCode",
"locale",
"requestedLocale",
"fallback",
"callingCode",
"nationalLengths",
"patterns",
"trunkPrefixRule",
"extensionSupported",
"hints",
"evidence"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: get_phone_input_rules
Diagnose dialing format
POST
/api/phone/diagnoseExplain formatting issues and propose reviewed prefix repairs for confirmation. Uses the same analyzer. Cannot determine why a network rejected a call.
MCP tool: diagnose_dialing_problem
Body parameters
phoneNumberstringrequired- Number to analyze. Use + and a country calling code for international input.
- Min characters: 1 · Max characters: 64
numberCountryCodestringoptional- Two-letter ISO country code for national input, such as GB. This identifies the numbering plan, not where the call starts.
- Pattern: ^[a-zA-Z]{2}$
originCountryCodestringoptional- Two-letter ISO country the call starts from. Required to interpret an international exit prefix.
- Pattern: ^[a-zA-Z]{2}$
detailstringoptional- Use full to include source evidence; compact keeps the response smaller.
- Values: compact, full · Default: "compact"
destinationCountryCodestringoptional- Two-letter ISO destination country for reviewed dialing guidance.
- Pattern: ^[a-zA-Z]{2}$
symptomstringoptional- What the caller observed. Network rejection cannot be diagnosed by formatting metadata.
- Values: format-rejected, call-failed, uncertain-format · Default: "uncertain-format"
devicestringoptional- The dialing device; unknown leaves device-dependent guidance conditional.
- Values: mobile, landline, unknown · Default: "unknown"
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/phone/diagnose' \
-H 'Content-Type: application/json' \
--data '{
"phoneNumber": "+4402079460123",
"numberCountryCode": "GB",
"symptom": "format-rejected"
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
analysisobjectrequiredShow child fields
statusstringrequired- Values: analyzed, needs-context, ambiguous, unsupported, invalid
canonicalInternationalstring | nullrequirednationalNumberstring | nullrequirednationalDisplaystring | nullrequiredinternationalDisplaystring | nullrequiredextensionstring | nullrequiredcategorystringrequired- Values: geographic, non-geographic, unknown
countryCandidatesarrayrequiredShow item fields
countryCodestringrequired- Two-letter ISO country code, for example GB.
namestringrequiredmatchedPrefixstringrequiredbasisstringrequired
checksobjectrequiredShow child fields
parsingstringrequired- Values: pass, fail, unknown, not-applicable
lengthstringrequired- Values: pass, fail, unknown, not-applicable
numberingPlanstringrequired- Values: pass, fail, unknown, not-applicable
reasonCodesarrayrequiredrequiredContextarrayrequiredtransformationsarrayrequiredShow item fields
rulestringrequiredactionstringrequired
evidenceIdsarrayrequiredevidencearrayoptionalShow item fields
idstringrequiredbasisstringrequired- Values: reviewed-guide, numbering-metadata
versionstringrequiredlastVerifiedstring | nullrequiredsourcesarrayrequiredShow item fields
urlstringrequiredpublisherstringrequiredtitlestringrequired
issuesarrayrequiredsuggestedCorrectionstring | nullrequiredsuggestionReasonstring | nullrequiredrequiredContextarrayrequiredunresolvedPossibilitiesarrayrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"analysis": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"analyzed",
"needs-context",
"ambiguous",
"unsupported",
"invalid"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"nationalNumber": {
"type": [
"string",
"null"
]
},
"nationalDisplay": {
"type": [
"string",
"null"
]
},
"internationalDisplay": {
"type": [
"string",
"null"
]
},
"extension": {
"type": [
"string",
"null"
]
},
"category": {
"type": "string",
"enum": [
"geographic",
"non-geographic",
"unknown"
]
},
"countryCandidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"countryCode": {
"type": "string"
},
"name": {
"type": "string"
},
"matchedPrefix": {
"type": "string"
},
"basis": {
"type": "string"
}
},
"required": [
"countryCode",
"name",
"matchedPrefix",
"basis"
],
"additionalProperties": false
}
},
"checks": {
"type": "object",
"properties": {
"parsing": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"length": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
},
"numberingPlan": {
"type": "string",
"enum": [
"pass",
"fail",
"unknown",
"not-applicable"
]
}
},
"required": [
"parsing",
"length",
"numberingPlan"
],
"additionalProperties": false
},
"reasonCodes": {
"type": "array",
"items": {
"type": "string"
}
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"rule",
"action"
],
"additionalProperties": false
}
},
"evidenceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"reviewed-guide",
"numbering-metadata"
]
},
"version": {
"type": "string"
},
"lastVerified": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"publisher": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"url",
"publisher",
"title"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"basis",
"version",
"lastVerified",
"sources"
],
"additionalProperties": false
}
}
},
"required": [
"status",
"canonicalInternational",
"nationalNumber",
"nationalDisplay",
"internationalDisplay",
"extension",
"category",
"countryCandidates",
"checks",
"reasonCodes",
"requiredContext",
"transformations",
"evidenceIds"
],
"additionalProperties": false
},
"issues": {
"type": "array",
"items": {
"type": "string"
}
},
"suggestedCorrection": {
"type": [
"string",
"null"
]
},
"suggestionReason": {
"type": [
"string",
"null"
]
},
"requiredContext": {
"type": "array",
"items": {
"type": "string"
}
},
"unresolvedPossibilities": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"analysis",
"issues",
"suggestedCorrection",
"suggestionReason",
"requiredContext",
"unresolvedPossibilities"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: diagnose_dialing_problem
Find calling windows
POST
/api/calling-windowsFind overlapping working hours using explicit IANA time zones and dates. Handles overnight shifts and DST; never infers location from phone numbers or contacts participants.
MCP tool: find_calling_windows
Body parameters
participantsarrayrequired- 1–8 participants with unique IDs and explicit IANA time zones.
- Min items: 1 · Max items: 8
Show item fields
idstringrequired- Min characters: 1 · Max characters: 64
timeZonestringrequired- IANA identifier such as Europe/London. Never inferred from a phone number.
- Max characters: 80
workingHoursarrayrequired- 1–4 local time intervals. Start and end must differ; overnight intervals are supported.
- Min items: 1 · Max items: 4
Show item fields
startstringrequired- Pattern: ^(?:[01][0-9]|2[0-3]):[0-5][0-9]$
endstringrequired- Pattern: ^(?:[01][0-9]|2[0-3]):[0-5][0-9]$
weekdaysarrayoptional- ISO weekday numbers: Monday is 1, Sunday is 7. Defaults to Monday–Friday.
- Default: [1,2,3,4,5] · Min items: 1 · Max items: 7
startDatestringrequired- First local shift-start date, YYYY-MM-DD, between 1970 and 2100.
- Pattern: ^\d{4}-\d{2}-\d{2}$
endDatestringrequired- Last local shift-start date, inclusive. The total date range must be 1–31 days.
- Pattern: ^\d{4}-\d{2}-\d{2}$
durationMinutesintegerrequired- Minimum overlap length, from 1 to 1440 minutes. Returned windows may be longer.
- Minimum: 1 · Maximum: 1440
limitintegeroptional- Default: 10 · Minimum: 1 · Maximum: 20
Responses
200 | Structured result; domain ambiguity and unsupported coverage are normal outcomes. |
400 | Invalid request or duplicate parameters. |
413 | Body exceeds 64 KiB. |
415 | Use uncompressed application/json. |
429 | Hosting rate limit, if enforced. Honor Retry-After when present. |
500 | Operation could not be completed. |
curl 'https://www.countrycalling.codes/api/calling-windows' \
-H 'Content-Type: application/json' \
--data '{
"participants": [
{
"id": "london",
"timeZone": "Europe/London",
"workingHours": [
{
"start": "09:00",
"end": "17:00"
}
]
},
{
"id": "new-york",
"timeZone": "America/New_York",
"workingHours": [
{
"start": "09:00",
"end": "17:00"
}
]
}
],
"startDate": "2026-09-08",
"endDate": "2026-09-08",
"durationMinutes": 30
}'200 response fields
metaobjectrequiredShow child fields
apiVersionstringrequireddatasetVersionstringrequirednumberingMetadataVersionstringrequiredprocessingstringrequired- Value: "ephemeral"
liveCarrierCheckbooleanrequired- Value: false
resultobjectrequiredShow child fields
windowsarrayrequiredShow item fields
startUtcstringrequiredendUtcstringrequireddurationMinutesnumberrequired- Minimum overlap length, from 1 to 1440 minutes. Returned windows may be longer.
participantsarrayrequired- 1–8 participants with unique IDs and explicit IANA time zones.
Show item fields
idstringrequiredtimeZonestringrequired- IANA identifier such as Europe/London. Never inferred from a phone number.
startLocalstringrequiredendLocalstringrequiredstartOffsetMinutesnumberrequiredendOffsetMinutesnumberrequired
truncatedbooleanrequiredpolicystringrequired
limitationsarrayrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"datasetVersion": {
"type": "string"
},
"numberingMetadataVersion": {
"type": "string"
},
"processing": {
"type": "string",
"const": "ephemeral"
},
"liveCarrierCheck": {
"type": "boolean",
"const": false
}
},
"required": [
"apiVersion",
"datasetVersion",
"numberingMetadataVersion",
"processing",
"liveCarrierCheck"
],
"additionalProperties": false
},
"result": {
"type": "object",
"properties": {
"windows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"startUtc": {
"type": "string"
},
"endUtc": {
"type": "string"
},
"durationMinutes": {
"type": "number"
},
"participants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timeZone": {
"type": "string"
},
"startLocal": {
"type": "string"
},
"endLocal": {
"type": "string"
},
"startOffsetMinutes": {
"type": "number"
},
"endOffsetMinutes": {
"type": "number"
}
},
"required": [
"id",
"timeZone",
"startLocal",
"endLocal",
"startOffsetMinutes",
"endOffsetMinutes"
],
"additionalProperties": false
}
}
},
"required": [
"startUtc",
"endUtc",
"durationMinutes",
"participants"
],
"additionalProperties": false
}
},
"truncated": {
"type": "boolean"
},
"policy": {
"type": "string"
}
},
"required": [
"windows",
"truncated",
"policy"
],
"additionalProperties": false
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"meta",
"result",
"limitations"
],
"additionalProperties": false
}Stable operation ID: find_calling_windows
Search and filter country calling codes
GET
/api/calling-codesSearch by natural language or filter by ISO country code, calling code, region, and limit. Add include=examples only when reviewed formatting guidance is needed.
MCP tool: lookup_country_calling_code
Path & query parameters
qstringoptional- Free-text search across country name, official name, ISO codes, calling code, capital, and area codes.
codestringoptional- ISO 3166-1 alpha-2 or alpha-3 code, such as GB or GBR.
dialCodestringoptional- Country calling code with or without plus sign, such as +44 or 44. This is not a complete E.164 phone number.
regionstringoptional- Region filter.
- Values: Africa, Americas, Asia, Europe, Oceania
limitintegeroptional- Maximum number of countries returned.
- Minimum: 1 · Maximum: 250
includestringoptional- Set to examples to include reviewed country dialingGuide content, safe display patterns, primary source URLs, and lastVerified metadata. Omitted by default.
- Values: examples
Responses
200 | Country calling-code results. |
400 | One or more query parameters are invalid. |
curl 'https://www.countrycalling.codes/api/calling-codes?code=GB&include=examples'200 response fields
metaobjectoptionalShow child fields
standardstringoptionalresultCountintegeroptionalincludesDialingGuidebooleanoptional
queryobjectoptionalcountriesarrayoptionalShow item fields
namestringrequiredofficialNamestringrequiredcodestringrequired- ISO 3166-1 alpha-2 code.
code3stringrequired- ISO 3166-1 alpha-3 code.
dialCodestringrequired- Country calling code such as +44. This is not a complete subscriber phone number.
dialCodeNumericintegerrequiredregionstringrequired- Values: Africa, Americas, Asia, Europe, Oceania
subregionstringrequiredcapitalstringrequiredflagstringrequiredtrunkPrefixstringoptional- Domestic prefix metadata. Do not remove it without applying a reviewed country-specific rule.
areaCodesarrayoptionalnotesstringoptionaldialingGuideobjectoptionalShow child fields
statusstringrequired- Value: "published"
countryCodestringrequired- Two-letter ISO country code, for example GB.
countryNamestringrequireddialCodestringrequiredanswerstringrequiredtrunkPrefixRulestringrequiredleadingZeroBehaviorstringrequired- Values: drop, retain, none, conditional
iddPrefixstringrequired- Origin-specific international direct dial prefix; not part of E.164.
iddPrefixStatusstringoptional- 'commonly-used' when iddPrefix is one of several operator-selected prefixes rather than a single national exit code.
- Values: standard, commonly-used
alternateIddPrefixesarrayoptionalmobileobjectoptionalShow child fields
kindstringrequired- Values: mobile, landline
nationalDisplaystringrequired- Safe domestic display pattern. X characters are placeholders.
internationalDisplaystringrequired- Safe international display pattern. It is not a dialable E.164 value when it contains X placeholders.
e164stringoptional- Optional digits-only E.164 example, included only when a safe reserved example is confirmed.
- Pattern: ^\+[1-9][0-9]{6,14}$
partsarrayrequiredShow item fields
valuestringrequiredlabelstringrequiredmeaningstringrequired
transformationstringrequirednotestringoptional
landlineobjectrequiredShow child fields
kindstringrequired- Values: mobile, landline
nationalDisplaystringrequired- Safe domestic display pattern. X characters are placeholders.
internationalDisplaystringrequired- Safe international display pattern. It is not a dialable E.164 value when it contains X placeholders.
e164stringoptional- Optional digits-only E.164 example, included only when a safe reserved example is confirmed.
- Pattern: ^\+[1-9][0-9]{6,14}$
partsarrayrequiredShow item fields
valuestringrequiredlabelstringrequiredmeaningstringrequired
transformationstringrequirednotestringoptional
carrierSelectionRulestringoptionalsharedPlanNotesstringoptionalterritoryNotesstringoptionalmnpCaveatstringrequiredformattingExceptionsarrayrequiredShow item fields
titlestringrequiredexplanationstringrequired
commonMistakesarrayrequiredreviewedBystringrequiredlastVerifiedstringrequiredsourcesarrayrequired- Min items: 1
Show item fields
publisherstringrequiredtitlestringrequiredurlstringrequiredpublishedAtstringoptionallastVerifiedstringrequired
slugstringrequiredurlstringrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"standard": {
"type": "string"
},
"resultCount": {
"type": "integer"
},
"includesDialingGuide": {
"type": "boolean"
}
}
},
"query": {
"type": "object"
},
"countries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Country"
}
}
}
}Stable operation ID: lookup_country_calling_code
Direct country calling-code lookup
GET
/api/calling-codes/{lookup}Lookup by ISO alpha-2, ISO alpha-3, country slug, exact country name, official name, or country calling code.
Path & query parameters
lookupstringrequired- Examples: gb, gbr, united-kingdom, 44, or %2B44.
includestringoptional- Set to examples to include reviewed country dialingGuide content, safe display patterns, primary source URLs, and lastVerified metadata. Omitted by default.
- Values: examples
Substitute path parameters in the URL. All remaining parameters are query parameters.
Responses
200 | One or more matching country calling-code records. |
400 | The lookup or include parameter is invalid. |
404 | No match found. |
curl 'https://www.countrycalling.codes/api/calling-codes/gb?include=examples'200 response fields
metaobjectoptionallookupstringoptionalcountriesarrayoptionalShow item fields
namestringrequiredofficialNamestringrequiredcodestringrequired- ISO 3166-1 alpha-2 code.
code3stringrequired- ISO 3166-1 alpha-3 code.
dialCodestringrequired- Country calling code such as +44. This is not a complete subscriber phone number.
dialCodeNumericintegerrequiredregionstringrequired- Values: Africa, Americas, Asia, Europe, Oceania
subregionstringrequiredcapitalstringrequiredflagstringrequiredtrunkPrefixstringoptional- Domestic prefix metadata. Do not remove it without applying a reviewed country-specific rule.
areaCodesarrayoptionalnotesstringoptionaldialingGuideobjectoptionalShow child fields
statusstringrequired- Value: "published"
countryCodestringrequired- Two-letter ISO country code, for example GB.
countryNamestringrequireddialCodestringrequiredanswerstringrequiredtrunkPrefixRulestringrequiredleadingZeroBehaviorstringrequired- Values: drop, retain, none, conditional
iddPrefixstringrequired- Origin-specific international direct dial prefix; not part of E.164.
iddPrefixStatusstringoptional- 'commonly-used' when iddPrefix is one of several operator-selected prefixes rather than a single national exit code.
- Values: standard, commonly-used
alternateIddPrefixesarrayoptionalmobileobjectoptionalShow child fields
kindstringrequired- Values: mobile, landline
nationalDisplaystringrequired- Safe domestic display pattern. X characters are placeholders.
internationalDisplaystringrequired- Safe international display pattern. It is not a dialable E.164 value when it contains X placeholders.
e164stringoptional- Optional digits-only E.164 example, included only when a safe reserved example is confirmed.
- Pattern: ^\+[1-9][0-9]{6,14}$
partsarrayrequiredShow item fields
valuestringrequiredlabelstringrequiredmeaningstringrequired
transformationstringrequirednotestringoptional
landlineobjectrequiredShow child fields
kindstringrequired- Values: mobile, landline
nationalDisplaystringrequired- Safe domestic display pattern. X characters are placeholders.
internationalDisplaystringrequired- Safe international display pattern. It is not a dialable E.164 value when it contains X placeholders.
e164stringoptional- Optional digits-only E.164 example, included only when a safe reserved example is confirmed.
- Pattern: ^\+[1-9][0-9]{6,14}$
partsarrayrequiredShow item fields
valuestringrequiredlabelstringrequiredmeaningstringrequired
transformationstringrequirednotestringoptional
carrierSelectionRulestringoptionalsharedPlanNotesstringoptionalterritoryNotesstringoptionalmnpCaveatstringrequiredformattingExceptionsarrayrequiredShow item fields
titlestringrequiredexplanationstringrequired
commonMistakesarrayrequiredreviewedBystringrequiredlastVerifiedstringrequiredsourcesarrayrequired- Min items: 1
Show item fields
publisherstringrequiredtitlestringrequiredurlstringrequiredpublishedAtstringoptionallastVerifiedstringrequired
slugstringrequiredurlstringrequired
{
"type": "object",
"properties": {
"meta": {
"type": "object"
},
"lookup": {
"type": "string"
},
"countries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Country"
}
}
}
}Stable operation ID: lookup_country_calling_code_direct
Format a phone number using reviewed country rules
POST
/api/phone/formatNormalizes an international number or converts a national-format number when a supported two-letter country code is supplied. Processing is ephemeral. This is formatting and plausibility guidance, not a live carrier, HLR/HSS, MNP, ownership, reachability, or consent check.
MCP tool: format_international_phone_number
Body parameters
phoneNumberstringrequired- Number to format. The value is processed ephemerally and is not stored.
- Min characters: 1 · Max characters: 64
countryCodestringoptional- Optional ISO 3166-1 alpha-2 context for national-format input.
- Pattern: ^[A-Za-z]{2}$
Responses
200 | Formatting or ambiguity result. |
400 | Invalid JSON, missing phone number, or unsupported country code. |
curl 'https://www.countrycalling.codes/api/phone/format' \
-H 'Content-Type: application/json' \
--data '{
"phoneNumber": "(020) 7946 0123",
"countryCode": "GB"
}'200 response fields
metaobjectrequiredinputobjectrequiredresultobjectrequiredShow child fields
statusstringrequired- Values: formatted, needs-country, ambiguous, invalid
originalstringrequirednormalizedCharactersstringrequiredextensionstring | nullrequiredprobableCountryobject | nullrequiredcanonicalInternationalstring | nullrequiredwarningsarrayrequiredambiguitystring | nullrequired
limitationsarrayrequired
{
"type": "object",
"required": [
"meta",
"input",
"result",
"limitations"
],
"properties": {
"meta": {
"type": "object"
},
"input": {
"type": "object"
},
"result": {
"type": "object",
"required": [
"status",
"original",
"normalizedCharacters",
"extension",
"probableCountry",
"canonicalInternational",
"warnings",
"ambiguity"
],
"properties": {
"status": {
"type": "string",
"enum": [
"formatted",
"needs-country",
"ambiguous",
"invalid"
]
},
"original": {
"type": "string"
},
"normalizedCharacters": {
"type": "string"
},
"extension": {
"type": [
"string",
"null"
]
},
"probableCountry": {
"type": [
"object",
"null"
]
},
"canonicalInternational": {
"type": [
"string",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"ambiguity": {
"type": [
"string",
"null"
]
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
}
}Stable operation ID: format_international_phone_number
Get live API status
GET
/api/calling-codes/statusPath & query parameters
No parameters.
Responses
200 | Live service version, timestamp, dataset counts and endpoint links. |
curl 'https://www.countrycalling.codes/api/calling-codes/status'200 response fields
statusstringrequired- Value: "ok"
servicestringrequiredversionstringrequiredtimestampstringrequireddatasetobjectrequiredendpointsobjectrequired
{
"type": "object",
"required": [
"status",
"service",
"version",
"timestamp",
"dataset",
"endpoints"
],
"properties": {
"status": {
"type": "string",
"const": "ok"
},
"service": {
"type": "string"
},
"version": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"dataset": {
"type": "object"
},
"endpoints": {
"type": "object"
}
}
}Stable operation ID: get_calling_codes_api_status
Connect with MCP
Add https://www.countrycalling.codes/api/mcp as a remote Streamable HTTP server in your MCP client. No credentials are required. Configuration syntax varies by client; select its HTTP transport option.
The server exposes 11 tools: country lookup, the original phone formatter, and nine phone workflows. Enhanced tools return structured content plus compact text summaries.
Use tools/list for tool schemas and tools/call for execution. Discover public capability and coverage resources through resources/list, and country input-rule templates through resources/templates/list.
A browser GET is a discovery response, not a tool execution. Connect through an MCP client for protocol initialization and calls.
https://www.countrycalling.codes/api/mcp{
"name": "analyze_phone_number",
"arguments": {
"phoneNumber": "(020) 7946 0123",
"numberCountryCode": "GB"
}
}OpenAPI & SDK generation
The OpenAPI 3.1 contract is the machine-readable reference. This page renders its parameters, required fields, constraints, and response schemas directly, including the shared REST/MCP workflow definitions.
Use stable operation IDs when generating a client. Keep SDK-specific naming changes in an overlay so the public contract and existing integrations remain compatible. No official generated SDK package is currently published; the examples above use standard HTTP clients.
For a Speakeasy workflow, install its agent skills in your SDK project and supply the OpenAPI URL. The skills guide authoring and generation; they are not a runtime dependency of this API.
npx skills add speakeasy-api/skillshttps://www.countrycalling.codes/api/calling-codes/openapi.jsonSDK generation and hosted tooling may have separate provider plans. They are optional.
API playground
Requests run only when you submit a form. Use synthetic examples when exploring the API.
Open phone workflow playground
POST /api/phone/analyze
Requests go to this service. Use synthetic examples here. Inputs are not saved by this explorer; external MCP clients and gateways may keep their own history.
Choose a workflow and run a request. Examples use synthetic numbers.
Open country lookup playground
Live API explorer
This form calls the deployed JSON route directly. No sample response is hard-coded.
Response
Select parameters and run the request.