{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Country Calling Codes API","version":"1.4.0","description":"Public read-only API for country calling codes, phone analysis, batch normalization, comparison, dialing guidance, input rules, and calling windows. Requests and responses use JSON. No authentication is required. Numbering metadata and reviewed evidence are distinct; neither establishes subscriber activity, reachability, ownership, or consent.","contact":{"name":"countrycalling.codes","url":"https://www.countrycalling.codes/contact"}},"servers":[{"url":"https://www.countrycalling.codes","description":"Production"}],"security":[],"tags":[{"name":"Calling codes"},{"name":"Phone formatting"},{"name":"Phone workflows"},{"name":"Service"}],"externalDocs":{"description":"Interactive API and MCP documentation","url":"https://www.countrycalling.codes/developers"},"paths":{"/api/capabilities":{"get":{"operationId":"get_phone_capabilities","summary":"Phone capabilities","description":"Discover supported countries, per-operation review coverage, evidence, dataset versions and request limits before choosing a phone workflow.","tags":["Phone workflows"],"parameters":[{"name":"countryCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z]{2}$"}},{"name":"operation","in":"query","required":false,"schema":{"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"]}}],"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"304":{"description":"Metadata unchanged (If-None-Match)."},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/phone/analyze":{"post":{"operationId":"analyze_phone_number","summary":"Analyze phone number","description":"Analyze a number using versioned numbering metadata. National numbers need numberCountryCode; exit prefixes need originCountryCode. Reports uncertainty and rule evidence, never live subscriber status.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"numberCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"}},"required":["phoneNumber"],"additionalProperties":false},"examples":{"basic":{"summary":"Analyze a phone number","value":{"phoneNumber":"(020) 7946 0123","numberCountryCode":"GB","detail":"full"}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/dialing/instructions":{"post":{"operationId":"get_dialing_instructions","summary":"Dialing instructions","description":"Prepare origin-specific dialing guidance for reviewed countries. Provide origin and destination separately; no phone number returns safe placeholder patterns. Network-dependent results remain conditional.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"destinationCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"device":{"type":"string","enum":["mobile","landline","unknown"],"default":"unknown"},"carrierSelectionCode":{"type":"string","pattern":"^[0-9]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"}},"required":["originCountryCode","destinationCountryCode"],"additionalProperties":false},"examples":{"basic":{"summary":"Prepare an international call","value":{"originCountryCode":"US","destinationCountryCode":"GB","phoneNumber":"+442079460123","device":"landline"}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/phone/batch":{"post":{"operationId":"normalize_phone_numbers","summary":"Normalize phone batch","description":"Normalize up to 100 records with unique IDs. Invalid records produce individual errors. Optionally identify canonical duplicate candidates; no contacts are changed or stored.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"phoneNumber":{"description":"For a successful record, provide a non-empty phone string up to 64 characters. Malformed values return a per-record error."},"numberCountryCode":{"description":"Optional two-letter ISO country context for this number."},"originCountryCode":{"description":"Optional two-letter ISO origin for interpreting an exit prefix."},"detail":{"description":"compact (default) or full to expand source evidence."}},"required":["id"],"additionalProperties":true},"minItems":1,"maxItems":100},"findDuplicates":{"type":"boolean","default":false}},"required":["items"],"additionalProperties":false},"examples":{"basic":{"summary":"Normalize a contact batch","value":{"items":[{"id":"a","phoneNumber":"020 7946 0123","numberCountryCode":"GB"},{"id":"b","phoneNumber":"+442079460123"},{"id":"c","phoneNumber":"5550100"}],"findDuplicates":true}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/phone/compare":{"post":{"operationId":"compare_phone_numbers","summary":"Compare phone numbers","description":"Compare two numbers after analysis. Missing context produces indeterminate. Extensions must match unless extensionPolicy is explicitly ignore; equality does not establish ownership.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"left":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"numberCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"}},"required":["phoneNumber"],"additionalProperties":false},"right":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"numberCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"}},"required":["phoneNumber"],"additionalProperties":false},"extensionPolicy":{"type":"string","enum":["exact","ignore"],"default":"exact"}},"required":["left","right"],"additionalProperties":false},"examples":{"basic":{"summary":"Compare two numbers","value":{"left":{"phoneNumber":"020 7946 0123","numberCountryCode":"GB"},"right":{"phoneNumber":"+442079460123"},"extensionPolicy":"exact"}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/phone/region":{"post":{"operationId":"resolve_phone_region","summary":"Resolve phone region","description":"Resolve a phone number to metadata-backed country candidates or non-geographic numbering. Results are numbering assignments, not current location or carrier.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"numberCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"}},"required":["phoneNumber"],"additionalProperties":false},"examples":{"basic":{"summary":"Resolve a numbering region","value":{"phoneNumber":"+442079460123"}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/countries/{code}/phone-input":{"get":{"operationId":"get_phone_input_rules","summary":"Phone input guidance","description":"Get reviewed display placeholders and trunk-prefix guidance. Examples are not validation masks. English fallback and unsupported editorial coverage are explicit.","tags":["Phone workflows"],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z]{2}$"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":35,"default":"en"}}],"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"304":{"description":"Metadata unchanged (If-None-Match)."},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/phone/diagnose":{"post":{"operationId":"diagnose_dialing_problem","summary":"Diagnose dialing format","description":"Explain formatting issues and propose reviewed prefix repairs for confirmation. Uses the same analyzer. Cannot determine why a network rejected a call.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64},"numberCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"originCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"detail":{"type":"string","enum":["compact","full"],"default":"compact"},"destinationCountryCode":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"symptom":{"type":"string","enum":["format-rejected","call-failed","uncertain-format"],"default":"uncertain-format"},"device":{"type":"string","enum":["mobile","landline","unknown"],"default":"unknown"}},"required":["phoneNumber"],"additionalProperties":false},"examples":{"basic":{"summary":"Diagnose a formatting problem","value":{"phoneNumber":"+4402079460123","numberCountryCode":"GB","symptom":"format-rejected"}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/calling-windows":{"post":{"operationId":"find_calling_windows","summary":"Find calling windows","description":"Find overlapping working hours using explicit IANA time zones and dates. Handles overnight shifts and DST; never infers location from phone numbers or contacts participants.","tags":["Phone workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"timeZone":{"type":"string","maxLength":80},"workingHours":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"}},"required":["start","end"],"additionalProperties":false},"minItems":1,"maxItems":4},"weekdays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7},"minItems":1,"maxItems":7,"default":[1,2,3,4,5]}},"required":["id","timeZone","workingHours"],"additionalProperties":false},"minItems":1,"maxItems":8},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"durationMinutes":{"type":"integer","minimum":1,"maximum":1440},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10}},"required":["participants","startDate","endDate","durationMinutes"],"additionalProperties":false},"examples":{"basic":{"summary":"Find overlapping calling hours","value":{"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}}}}}},"responses":{"200":{"description":"Structured result; domain ambiguity and unsupported coverage are normal outcomes.","content":{"application/json":{"schema":{"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}}}},"400":{"description":"Invalid request or duplicate parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 64 KiB."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Hosting rate limit, if enforced. Honor Retry-After when present."},"500":{"description":"Operation could not be completed."}}}},"/api/calling-codes":{"get":{"tags":["Calling codes"],"operationId":"lookup_country_calling_code","summary":"Search and filter country calling codes","description":"Search by natural language or filter by ISO country code, calling code, region, and limit. Add include=examples only when reviewed formatting guidance is needed.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search across country name, official name, ISO codes, calling code, capital, and area codes."},{"name":"code","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 or alpha-3 code, such as GB or GBR."},{"name":"dialCode","in":"query","schema":{"type":"string"},"description":"Country calling code with or without plus sign, such as +44 or 44. This is not a complete E.164 phone number."},{"name":"region","in":"query","schema":{"type":"string","enum":["Africa","Americas","Asia","Europe","Oceania"]},"description":"Region filter."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":250},"description":"Maximum number of countries returned."},{"name":"include","in":"query","schema":{"type":"string","enum":["examples"]},"description":"Set to examples to include reviewed country dialingGuide content, safe display patterns, primary source URLs, and lastVerified metadata. Omitted by default."}],"responses":{"200":{"description":"Country calling-code results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallingCodesResponse"}}}},"400":{"description":"One or more query parameters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calling-codes/{lookup}":{"get":{"tags":["Calling codes"],"operationId":"lookup_country_calling_code_direct","summary":"Direct country calling-code lookup","description":"Lookup by ISO alpha-2, ISO alpha-3, country slug, exact country name, official name, or country calling code.","parameters":[{"name":"lookup","in":"path","required":true,"schema":{"type":"string"},"description":"Examples: gb, gbr, united-kingdom, 44, or %2B44."},{"name":"include","in":"query","schema":{"type":"string","enum":["examples"]},"description":"Set to examples to include reviewed country dialingGuide content, safe display patterns, primary source URLs, and lastVerified metadata. Omitted by default."}],"responses":{"200":{"description":"One or more matching country calling-code records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectLookupResponse"}}}},"400":{"description":"The lookup or include parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No match found."}}}},"/api/phone/format":{"post":{"tags":["Phone formatting"],"operationId":"format_international_phone_number","summary":"Format a phone number using reviewed country rules","description":"Normalizes 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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneFormatRequest"}}}},"responses":{"200":{"description":"Formatting or ambiguity result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneFormatResponse"}}}},"400":{"description":"Invalid JSON, missing phone number, or unsupported country code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calling-codes/status":{"get":{"tags":["Service"],"operationId":"get_calling_codes_api_status","summary":"Get live API status","responses":{"200":{"description":"Live service version, timestamp, dataset counts and endpoint links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error","documentation"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_REQUEST"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"documentation":{"type":"string","format":"uri"}}},"StatusResponse":{"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"}}},"SourceReference":{"type":"object","required":["publisher","title","url","lastVerified"],"properties":{"publisher":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publishedAt":{"type":"string","format":"date"},"lastVerified":{"type":"string","format":"date"}}},"DialingPart":{"type":"object","required":["value","label","meaning"],"properties":{"value":{"type":"string"},"label":{"type":"string"},"meaning":{"type":"string"}}},"DialingExample":{"type":"object","required":["kind","nationalDisplay","internationalDisplay","parts","transformation"],"properties":{"kind":{"type":"string","enum":["mobile","landline"]},"nationalDisplay":{"type":"string","description":"Safe domestic display pattern. X characters are placeholders."},"internationalDisplay":{"type":"string","description":"Safe international display pattern. It is not a dialable E.164 value when it contains X placeholders."},"e164":{"type":"string","pattern":"^\\+[1-9][0-9]{6,14}$","description":"Optional digits-only E.164 example, included only when a safe reserved example is confirmed."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/DialingPart"}},"transformation":{"type":"string"},"note":{"type":"string"}}},"FormattingException":{"type":"object","required":["title","explanation"],"properties":{"title":{"type":"string"},"explanation":{"type":"string"}}},"DialingGuide":{"type":"object","required":["status","countryCode","countryName","dialCode","answer","trunkPrefixRule","leadingZeroBehavior","iddPrefix","mobile","landline","mnpCaveat","formattingExceptions","commonMistakes","reviewedBy","lastVerified","sources"],"properties":{"status":{"type":"string","const":"published"},"countryCode":{"type":"string"},"countryName":{"type":"string"},"dialCode":{"type":"string"},"answer":{"type":"string"},"trunkPrefixRule":{"type":"string"},"leadingZeroBehavior":{"type":"string","enum":["drop","retain","none","conditional"]},"iddPrefix":{"type":"string","description":"Origin-specific international direct dial prefix; not part of E.164."},"alternateIddPrefixes":{"type":"array","items":{"type":"string"}},"mobile":{"$ref":"#/components/schemas/DialingExample"},"landline":{"$ref":"#/components/schemas/DialingExample"},"carrierSelectionRule":{"type":"string"},"sharedPlanNotes":{"type":"string"},"territoryNotes":{"type":"string"},"mnpCaveat":{"type":"string"},"formattingExceptions":{"type":"array","items":{"$ref":"#/components/schemas/FormattingException"}},"commonMistakes":{"type":"array","items":{"type":"string"}},"reviewedBy":{"type":"string"},"lastVerified":{"type":"string","format":"date"},"sources":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/SourceReference"}}}},"Country":{"type":"object","required":["name","officialName","code","code3","dialCode","dialCodeNumeric","region","subregion","capital","flag","slug","url"],"properties":{"name":{"type":"string"},"officialName":{"type":"string"},"code":{"type":"string","description":"ISO 3166-1 alpha-2 code."},"code3":{"type":"string","description":"ISO 3166-1 alpha-3 code."},"dialCode":{"type":"string","description":"Country calling code such as +44. This is not a complete subscriber phone number."},"dialCodeNumeric":{"type":"integer"},"region":{"type":"string","enum":["Africa","Americas","Asia","Europe","Oceania"]},"subregion":{"type":"string"},"capital":{"type":"string"},"flag":{"type":"string"},"trunkPrefix":{"type":"string","description":"Domestic prefix metadata. Do not remove it without applying a reviewed country-specific rule."},"areaCodes":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"dialingGuide":{"$ref":"#/components/schemas/DialingGuide"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"}}},"CallingCodesResponse":{"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"}}}},"DirectLookupResponse":{"type":"object","properties":{"meta":{"type":"object"},"lookup":{"type":"string"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}},"PhoneFormatRequest":{"type":"object","required":["phoneNumber"],"additionalProperties":false,"properties":{"phoneNumber":{"type":"string","minLength":1,"maxLength":64,"description":"Number to format. The value is processed ephemerally and is not stored.","example":"(020) 7946 0123"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Optional ISO 3166-1 alpha-2 context for national-format input.","example":"GB"}}},"PhoneFormatResponse":{"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"}}}}}}}