Country Code Inference for Partial Phone Numbers Prompt Template

This prompt is designed for telecom integrators and data engineers who receive partial phone numbers from model outputs—numbers missing country codes, containing ambiguous local formats, or stripped of international prefixes during extraction. The job-to-be-done is inferring the most likely E.164 country code from available context clues (other fields in the record, user locale, language signals, or explicit hints in surrounding text) and producing a complete, dialable number with a confidence flag. The ideal user is building an identity resolution pipeline, a CRM ingestion workflow, or a customer data platform where incomplete numbers block deduplication and downstream routing.

Use this prompt when you have a partial number and at least one contextual signal—a billing country, a user-provided locale, a language preference, or a known region from a related record. The prompt is not a general-purpose phone validator; it assumes the number itself is syntactically plausible but missing the country prefix. Do not use this prompt when you have zero context (the model will guess, and the confidence flag will be low, but the output may still be misleading), when the number is already in full E.164 format (use a canonicalization prompt instead), or when the number is so malformed that digit-level repair is required before country code inference can begin. For high-volume pipelines, pair this prompt with a pre-filter that separates already-complete numbers from partial ones to avoid unnecessary inference calls.

The prompt produces a structured output containing the inferred country code, the completed E.164 number, a confidence score, and a reasoning trace. Ambiguous cases are the primary failure mode: numbers like 2025550142 could be Washington, DC (+1) or a subset of other North American numbering plan digits. The prompt is designed to flag these ambiguities rather than silently pick a winner. Before wiring this into production, you must decide your threshold for auto-acceptance versus human review, and you should test against a golden set of ambiguous cases where multiple countries share overlapping number patterns. The next section provides the copy-ready template with placeholders for your specific inputs, constraints, and risk tolerance.

This prompt template is designed to take a partial phone number—one that may be missing its country code—along with available context clues, and return a complete E.164-formatted number with an inferred country code and a confidence flag. The template uses square-bracket placeholders that you replace with actual values in your application code before sending the request to the model. The core job is disambiguation: when a number like 555-0123 could belong to multiple countries, the model must weigh contextual signals such as user locale, address fields, or surrounding text to make the best inference.

textCopy
You are a phone number normalization specialist. Your task is to infer the missing country code for a partial phone number and return a complete E.164-formatted number.

INPUT NUMBER: [PARTIAL_NUMBER]
CONTEXT CLUES (may be empty): [CONTEXT]
USER LOCALE (ISO 3166-1 alpha-2, may be empty): [LOCALE]

RULES:
1. If the input number already includes a valid country code, return it as-is in E.164 format.
2. If the country code is missing, infer the most likely country code using the context clues and user locale.
3. If multiple countries share the number pattern, use context to disambiguate. If context is insufficient, default to the user locale's country code.
4. If no inference is possible, set the country code to null and flag the output.
5. Strip any leading zeros, trunk prefixes, or non-numeric characters before formatting.
6. Return ONLY valid JSON matching the output schema. No explanatory text.

OUTPUT SCHEMA:
{
  "original_input": "string (the input as received)",
  "e164_number": "string (complete E.164 number with + and country code, or null if impossible)",
  "inferred_country_code": "string (ISO 3166-1 alpha-2, or null)",
  "confidence": "high | medium | low | none",
  "reasoning": "string (brief explanation of inference logic)",
  "requires_human_review": true | false
}

CONSTRAINTS:
- Do not invent area codes or subscriber numbers not present in the input.
- If the input appears to be a local number without enough context, flag for human review.
- For numbers in the North American Numbering Plan (NXX-NXX-XXXX patterns), default to US (+1) unless context strongly indicates Canada or another NANP country.
- For UK numbers starting with 07, infer +44.
- For numbers matching mobile patterns in multiple EU countries, use locale as tiebreaker.

To adapt this template, replace each bracketed placeholder with real data from your pipeline. [PARTIAL_NUMBER] should be the raw number string from the model output. [CONTEXT] should include any surrounding text, address fields, or user-provided location hints. [LOCALE] should be a two-letter country code from your application's user session or request metadata. In production, always validate the returned JSON against the output schema before accepting the inference. For high-risk telecom or compliance workflows, route any output with confidence: "low" or requires_human_review: true to a review queue rather than writing it directly to your system of record.

This prompt is designed to be called as a post-processing step after a model has extracted or generated a partial phone number. It should not be the primary extraction prompt. Wire it into your pipeline immediately after phone number extraction and before the number is written to your canonical data store or passed to a downstream telephony API. The harness must treat the model's output as a structured repair suggestion, not as an authoritative result—every inferred country code must pass through validation and confidence checks before acceptance.

Input assembly: Collect the partial phone number string, any available locale hints (user language, shipping country, IP geolocation), and the original context where the number appeared. Pack these into the [PARTIAL_NUMBER], [LOCALE_HINTS], and [SOURCE_CONTEXT] placeholders. If no locale hints exist, pass an explicit null or empty object—do not omit the field, as the prompt's instructions depend on knowing when hints are absent. For batch processing, send one record per call; batching multiple numbers in a single prompt increases the risk of cross-record contamination and makes per-record confidence scoring unreliable.

Model choice and configuration: Use a model with strong instruction-following and low hallucination rates on structured tasks—GPT-4o, Claude 3.5 Sonnet, or equivalent. Set temperature=0 to maximize deterministic behavior. Enable structured output mode (JSON mode or tool calling with a defined schema) to enforce the [OUTPUT_SCHEMA] contract. The output must include inferred_country_code, complete_e164, confidence (a float 0.0–1.0), alternative_codes (array of other plausible codes), and reasoning (a brief string explaining the inference). If the model cannot produce valid JSON, fail closed—do not attempt to parse a free-text response.

Validation layer: Before accepting the output, run these checks: (1) The complete_e164 string must match the E.164 regex pattern ^\+[1-9]\d{1,14}$. (2) The inferred_country_code must appear in a hardcoded allowlist of valid ITU country calling codes. (3) If confidence < 0.85, route the record to a human review queue with the original partial number, the model's reasoning, and the alternative codes. (4) If alternative_codes contains a code with a confidence delta of less than 0.15 from the primary, flag the record as ambiguous—this often happens with North American numbers (+1 shared by US, Canada, and several Caribbean nations) or numbers in the +7 shared region. (5) Verify that the national significant number portion of the E.164 output is consistent with the input partial number; the model should not invent or drop digits.

Retry and fallback strategy: If validation fails due to malformed JSON or schema violations, retry once with the same input and an explicit error message appended to the prompt (e.g., 'Previous output failed validation: [ERROR_DETAIL]. Please correct and return valid JSON only.'). If the second attempt fails or if confidence remains below threshold after retry, do not retry further—escalate to human review. For high-throughput pipelines, implement a dead-letter queue for records that fail after max retries, and monitor the failure rate to detect prompt drift or model behavior changes.

Logging and observability: Log every inference with: input partial number (hashed if PII-sensitive), locale hints, model version, prompt version, raw output, validation result, confidence score, and final disposition (accepted, reviewed, rejected). This trace is essential for debugging ambiguous cases—especially shared country code regions—and for calibrating the confidence threshold over time. If your application operates in regulated telecom or financial contexts, these logs are also your audit evidence that inference decisions were reviewed and not applied blindly.