Phone Number Canonicalization Prompt Template

This prompt is designed for identity resolution pipelines, customer data platform (CDP) operators, and CRM integrators who need to ingest phone numbers from unstructured or semi-structured model outputs and convert them into a clean, deduplicatable, E.164-formatted canonical form. The primary job-to-be-done is to take a raw phone number string—potentially containing extensions, vanity characters, country codes, or local formatting—and produce a structured object with a normalized number, a country code, a type classification (mobile, landline, VoIP), and a confidence score. The ideal user is a data engineer or backend developer building an automated data ingestion or identity stitching workflow where downstream systems require strict format compliance.

Use this prompt when you have already extracted a phone number from a larger text but the format is inconsistent. It is not a general-purpose extraction prompt; it assumes a phone number candidate is already isolated. The prompt is most effective when you can provide additional context, such as a default country code for local numbers or a user's locale, to resolve ambiguous cases. It is designed to be wired into a post-processing repair loop, where a validation failure on a phone number field triggers this canonicalization step before the record is written to a system of record. The prompt includes instructions for the model to flag ambiguous numbers for human review rather than guessing, which is critical for high-stakes applications like two-factor authentication or compliance-mandated contact verification.

Do not use this prompt for real-time, sub-millisecond validation where a deterministic regex library like Google's libphonenumber would suffice. The prompt is for repair and disambiguation, not for initial format checking. It is also not a substitute for a full contact deduplication pipeline; it standardizes a single identifier, not a complete record. Avoid using this prompt on raw, multi-line text blobs containing multiple phone numbers—pair it with an extraction prompt first. The next step after reading this section is to review the prompt template, adapt the placeholders to your application's context, and integrate it into a validation harness that can measure false-positive canonicalization rates against a golden dataset of known numbers.

This prompt template is designed to be dropped into an identity resolution pipeline, a CRM ingestion workflow, or a post-generation repair loop. It takes a raw phone number string—potentially malformed, missing a country code, or carrying an extension—and produces a structured, E.164-compliant output with explicit reasoning. The template uses square-bracket placeholders for all variable inputs so you can adapt it to your own validation rules, default country, and output schema without rewriting the core instruction.

textCopy
You are a phone number canonicalization engine. Your job is to convert a raw phone number string into a clean, E.164-formatted number with country code inference, extension normalization, and type classification.

## INPUT
Raw phone number: [INPUT]

## CONTEXT
- Default country for inference when no country code is present: [DEFAULT_COUNTRY_CODE]
- Known valid country codes in our system: [VALID_COUNTRY_CODES]
- Extension separator preferences: [EXTENSION_SEPARATORS]

## OUTPUT SCHEMA
Return a JSON object with exactly these fields:
{
  "original": "string (the raw input)",
  "e164": "string (E.164 formatted number or null if unrepairable)",
  "country_code": "string (ISO 3166-1 alpha-2 or null)",
  "national_number": "string (national significant number without country code)",
  "extension": "string or null",
  "type": "string (one of: mobile, fixed_line, voip, toll_free, premium_rate, shared_cost, personal_number, pager, uan, unknown)",
  "is_valid": boolean,
  "confidence": "string (one of: high, medium, low)",
  "repair_actions": ["string (list of transformations applied, e.g., 'added_country_code', 'stripped_formatting', 'normalized_extension')"],
  "warnings": ["string (any concerns about the result, e.g., 'ambiguous_country_code', 'number_too_short')"]
}

## CONSTRAINTS
1. Always strip non-digit characters except the leading '+' and any extension separator specified in [EXTENSION_SEPARATORS].
2. If no country code is present, infer from [DEFAULT_COUNTRY_CODE] and mark confidence as 'medium' with warning 'inferred_country_code'.
3. If the number matches patterns for multiple countries in [VALID_COUNTRY_CODES], mark confidence as 'low' with warning 'ambiguous_country_code' and list the alternatives in warnings.
4. If the number is unrepairable (fewer than 7 digits after stripping, or contains alphabetic characters that aren't extension labels), set e164 to null, is_valid to false, and explain in warnings.
5. For extensions, strip any label like 'ext', 'x', or 'extension' and store only the numeric portion.
6. Do not invent digits. If you cannot determine the correct number, mark it invalid rather than guessing.

## EXAMPLES
Input: "(415) 555-2671"
Default country: "US"
Output: {"original": "(415) 555-2671", "e164": "+14155552671", "country_code": "US", "national_number": "4155552671", "extension": null, "type": "fixed_line", "is_valid": true, "confidence": "medium", "repair_actions": ["stripped_formatting", "added_country_code"], "warnings": ["inferred_country_code"]}

Input: "+44 20 7946 0958"
Default country: "US"
Output: {"original": "+44 20 7946 0958", "e164": "+442079460958", "country_code": "GB", "national_number": "2079460958", "extension": null, "type": "fixed_line", "is_valid": true, "confidence": "high", "repair_actions": ["stripped_formatting"], "warnings": []}

Input: "555-1234 ext. 201"
Default country: "US"
Output: {"original": "555-1234 ext. 201", "e164": "+15551234", "country_code": "US", "national_number": "5551234", "extension": "201", "type": "unknown", "is_valid": true, "confidence": "low", "repair_actions": ["stripped_formatting", "added_country_code", "normalized_extension"], "warnings": ["inferred_country_code", "number_too_short"]}

Input: "not-a-number"
Default country: "US"
Output: {"original": "not-a-number", "e164": null, "country_code": null, "national_number": null, "extension": null, "type": "unknown", "is_valid": false, "confidence": "low", "repair_actions": [], "warnings": ["unrepairable_input"]}

## RISK LEVEL
[RISK_LEVEL]

If RISK_LEVEL is 'high', add an additional field "requires_human_review": boolean to the output and set it to true whenever confidence is 'low' or warnings contains 'ambiguous_country_code'.

To adapt this template, replace each square-bracket placeholder with your pipeline's configuration. For a CRM ingestion workflow, set [DEFAULT_COUNTRY_CODE] to your primary market, [VALID_COUNTRY_CODES] to the ISO codes you accept, and [EXTENSION_SEPARATORS] to ["ext", "x", "extension"]. If you are running in a high-risk identity resolution pipeline, set [RISK_LEVEL] to "high" to enable the mandatory human-review flag. For batch processing, wrap this prompt in a loop that feeds one raw number per call and validates each JSON response against the schema before writing to your canonical data store. Always log the repair_actions and warnings fields to your observability system so you can monitor how often the model is inferring country codes or flagging ambiguous numbers.

The phone number canonicalization prompt is designed to be called as a stateless function inside a data pipeline or API handler. It accepts a raw phone number string and optional context (such as a default country code or user locale) and returns a structured E.164 payload. The prompt should be treated as a post-extraction repair step, not a real-time user-facing feature. Wire it after your initial extraction or generation step, and before any downstream CRM write, identity resolution match, or SMS send operation. The prompt expects the model to reason about ambiguous cases (e.g., a 10-digit number that could be local in multiple countries), so always provide a [DEFAULT_COUNTRY] hint when available to reduce disambiguation errors.

Validation and retry logic must sit outside the prompt. After the model returns a JSON payload, validate the e164 field against a strict E.164 regex (e.g., ^\+[1-9]\d{1,14}$). If validation fails, retry once with the error message injected into the prompt's [PREVIOUS_ERROR] placeholder. If the second attempt also fails, log the raw input, the model's output, and the validation error, then route the record to a human review queue. Do not silently drop invalid numbers—they often represent edge cases worth fixing. For high-throughput pipelines, implement a circuit breaker that halts processing if the failure rate exceeds 5% over a rolling window of 100 calls, preventing cascading bad outputs from polluting your canonical data store.

Model choice matters. Use a model with strong instruction-following and JSON output discipline, such as GPT-4o, Claude 3.5 Sonnet, or a fine-tuned variant if you have sufficient training data. Avoid smaller or older models that struggle with the structured output format and country code inference simultaneously. Enable structured output mode (JSON mode or function calling with a strict schema) to reduce parsing failures. Log every call with the prompt_version, model_id, input_hash, output_e164, confidence_score, and validation_passed fields. This audit trail is essential for debugging disambiguation errors and proving data quality to downstream consumers. For batch processing, implement rate limiting and exponential backoff to handle API throttling gracefully.

When to escalate beyond a prompt: If your pipeline processes more than 10,000 numbers per day, the latency and cost of LLM-based canonicalization may become prohibitive. In that case, use the prompt to build a labeled dataset of raw-to-canonical pairs, then train a lightweight classifier or deterministic rule engine for the common cases, reserving the LLM prompt only for ambiguous or low-confidence inputs. Similarly, if your use case requires real-time canonicalization (e.g., during live call routing), the prompt's latency is too high; pre-compute canonical forms or use a deterministic library like Google's libphonenumber for the fast path, falling back to the LLM prompt only when the library returns an invalid or ambiguous result. Never use this prompt as the sole validation step before sending SMS or making phone calls—always confirm the number is reachable through a separate verification channel.