Social Handle Extraction and Normalization Prompt Template

This prompt is designed for identity resolution pipelines, social CRM integrators, and data engineering teams that need to extract social media handles from unstructured or semi-structured model outputs. The primary job is to take a messy text block—such as a bio, a scraped profile, or a free-text notes field—and return a clean, normalized list of platform-attributed handles. The prompt handles common normalization tasks: stripping @ prefixes, converting profile URLs to bare handles (e.g., https://twitter.com/username → username), and detecting the platform when it is implied but not explicitly stated. Use this when downstream systems require deduplicatable, platform-tagged identifiers for matching, enrichment, or analytics.

The ideal input is a short-to-medium length text field (under 2,000 tokens) that contains one or more social media references. The prompt works best when the platform is either explicitly named, implied by domain (e.g., linkedin.com/in/...), or inferable from handle conventions. Do not use this prompt for bulk extraction from large document corpora without chunking; it is not designed for long-context retrieval. Do not use it as a real-time entity linker that must resolve handles against a live identity graph—this prompt normalizes what is present, it does not verify that a handle exists or belongs to a specific person. For verification, pair the output with a separate API lookup step. If the input contains deliberately obfuscated handles (e.g., user [at] domain), expect degraded performance and consider a pre-processing regex layer.

Before wiring this into a production pipeline, define your ambiguity tolerance. The prompt includes a platform disambiguation step, but when a handle could belong to multiple platforms (e.g., a common username without a domain hint), the model must either guess with a confidence flag or return the handle as platform: unknown. Decide which behavior your downstream system can tolerate. For high-stakes identity resolution where a wrong platform attribution causes a broken match, route ambiguous outputs to a human review queue. The eval harness described later in this playbook includes test cases for exactly these ambiguous scenarios. Start by running the prompt against a labeled dataset of 50–100 real-world examples from your own data before integrating it into an automated pipeline.

This prompt template is designed to extract social media handles from model-generated text, user-submitted content, or scraped data and normalize them into a consistent, application-ready format. It handles platform detection, @ prefix stripping, URL-to-handle conversion, and ambiguous platform attribution. Use this template as the core instruction block in your extraction pipeline, then wrap it with the validation, retry, and evaluation harness described in the implementation section.

textCopy
You are a social handle extraction and normalization engine. Your job is to extract social media handles from the provided text and return them in a clean, structured format.

## INPUT
[INPUT]

## PLATFORM CONTEXT (OPTIONAL)
[CONTEXT]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "handles": [
    {
      "platform": "string (twitter, linkedin, github, instagram, youtube, tiktok, facebook, other)",
      "handle": "string (normalized, no @ prefix, no URL)",
      "original_text": "string (the exact text span the handle was extracted from)",
      "confidence": "high|medium|low",
      "is_ambiguous_platform": true|false,
      "alternative_platforms": ["string"]
    }
  ],
  "extraction_notes": ["string"]
}

## NORMALIZATION RULES
1. Strip @ prefixes from all handles.
2. If the input contains a URL (e.g., https://twitter.com/username, https://linkedin.com/in/username), extract only the handle portion.
3. Convert handles to lowercase for case-insensitive platforms (Twitter, Instagram). Preserve case for case-sensitive platforms (GitHub).
4. Remove trailing slashes, query parameters, and fragments from URL-derived handles.
5. If a handle appears multiple times in the input, return it once with the highest-confidence extraction.
6. Do not invent handles. Only extract handles explicitly present in the input text.

## PLATFORM DETECTION RULES
- If the input contains a platform-specific URL (twitter.com, linkedin.com/in, github.com, etc.), assign that platform.
- If the handle appears with a platform label (e.g., "Twitter: @user", "GitHub: user"), use that label.
- If platform is ambiguous, set is_ambiguous_platform to true and list alternative_platforms.
- Use [CONTEXT] as a hint for platform disambiguation when provided.

## CONFIDENCE RULES
- high: Platform is explicit from URL or label, and handle format matches platform conventions.
- medium: Platform is inferred from handle format or context, but not explicit.
- low: Handle extracted but platform is ambiguous with no strong signal.

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Return ONLY the JSON object. No markdown fences, no commentary.

To adapt this template, replace the square-bracket placeholders with your specific requirements. [INPUT] should contain the raw text you want to extract handles from. [CONTEXT] is optional but valuable when you have prior knowledge about which platforms are likely (e.g., "this is a developer portfolio page, expect GitHub and LinkedIn"). [CONSTRAINTS] can include platform allowlists or blocklists (e.g., "only extract Twitter and LinkedIn handles"), maximum handle count, or domain-specific rules. [EXAMPLES] should include few-shot demonstrations covering edge cases like URL-embedded handles, handles with special characters, and ambiguous platform signals. [RISK_LEVEL] should be set to low, medium, or high to control whether the extraction pipeline requires human review for low-confidence results. For high-risk identity resolution workflows, always set RISK_LEVEL to high and route low-confidence extractions to a human review queue before they enter your CRM or CDP.

Before deploying this prompt, test it against a golden dataset that includes: handles embedded in narrative text, handles inside markdown links, handles with non-standard characters, multiple handles from different platforms in one input, and inputs with no handles at all. The most common failure mode is over-extraction—the model inventing handles from names or email addresses. Mitigate this by including negative examples in your few-shot demonstrations and by running the output through the hallucination detection harness described in the implementation section. If you are processing user-generated content at scale, also test for prompt injection attempts where malicious input tries to override the normalization rules.

This prompt is designed to sit inside a post-generation repair or normalization pipeline, not as a standalone user-facing feature. The typical integration point is after a model has produced unstructured or semi-structured text containing social handles—such as a contact enrichment step, a CRM import, or an identity resolution workflow. The harness receives the raw model output, injects it into the prompt template as [RAW_TEXT], and expects a structured JSON response with normalized handles, platform classifications, and confidence flags. Because the prompt handles both @-style mentions and URL-to-handle conversion, the harness should not pre-process or strip the input before sending it; let the prompt own the extraction logic.

Validation and retry logic is critical here. The harness must validate the returned JSON against a schema that enforces: handles as an array of objects with required fields handle (string, no @ prefix), platform (enum of supported platforms), confidence (0-1 float), and optional original_text and normalization_notes. If validation fails, implement a single retry with the validation error message appended to [CONSTRAINTS] as 'Previous output failed validation: [error]. Correct the output.' Do not retry more than once for the same input—escalate to a human review queue instead. For ambiguous platform attribution where confidence is below 0.7, the harness should route the record to a review queue rather than silently accepting the model's best guess. This is especially important for handles that could belong to multiple platforms (e.g., a short alphanumeric string that exists on both Twitter and GitHub).

Model choice and latency considerations matter for batch versus real-time use. For batch normalization of CRM records, a slower but more accurate model (GPT-4o, Claude 3.5 Sonnet) is appropriate, and you can process records in chunks of 50-100 with a 30-second timeout per chunk. For real-time identity resolution where latency must stay under 2 seconds, use a faster model (GPT-4o-mini, Claude 3.5 Haiku) and process handles one at a time. Logging should capture: the raw input, the normalized output, validation pass/fail, retry count, platform confidence distribution, and any records routed to human review. This log becomes your eval dataset for measuring extraction accuracy over time. Tool use is not required for this prompt—the extraction and normalization logic is self-contained. However, if you have an internal platform validation API (e.g., checking whether a handle actually exists on a platform), wire it as a post-processing step after the prompt returns, not as a tool the model calls during extraction.

What to avoid: Do not use this prompt for real-time user-facing features where a hallucinated handle could cause a bad user experience (e.g., auto-populating a profile field). Always add a human review step for high-confidence actions like sending messages or merging contact records. Do not skip the confidence threshold check—ambiguous platform attribution is the most common failure mode, and silently misattributing a handle to the wrong platform creates data quality debt that compounds across downstream systems. If you're processing handles from user-generated content where the model might extract non-handle text as handles (e.g., email addresses, hashtags), add a post-extraction filter that rejects extracted strings matching known non-handle patterns before they enter your canonicalization pipeline.