openapi: 3.2.0 info: title: Country Calling Codes Phone workflows 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: Phone workflows 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. 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 externalDocs: description: Interactive API and MCP documentation url: https://www.countrycalling.codes/developers