Imported from seanpjones-collab/SiftStack (.claude/skills/phone-validator/SKILL.md). Install upstream with npx skills add seanpjones-collab/SiftStack --skill phone-validator. Copyright stays with the author.

Phone Validator & Tagger

Score phone numbers using Trestle's phone_intel API and produce DataSift/REISift-ready CSVs with phone tags for prioritized dialing.

What This Skill Does

This skill takes a CSV of phone numbers — typically a DataSift "Phone Enrichment" export with Phone 1 through Phone 30 columns — runs each unique number through Trestle's Phone Validation API to get an activity score and line type, then assigns a phone tag tier based on configurable score thresholds. The output is a two-column CSV (Phone Number, Phone Tag) formatted for direct upload to DataSift/REISift using their "Update Data → Tag phones by phone number" workflow.

The Pipeline

Input CSV (DataSift Phone Enrichment export or any CSV with phone columns)
  → Parse all phone columns (Phone 1 through Phone 30)
    → Deduplicate across all columns and rows (saves API cost)
      → ESTIMATE COST & GET USER CONFIRMATION
        → Trestle phone_intel API (activity_score + line_type)
          → Score-based tier assignment (Dial First, Dial Second, Dial Third, Dial Fourth, Drop)
            → DataSift-ready CSV (Phone Number | Phone Tag)
              → Upload to DataSift via "Update Data → Tag phones by phone number"

How to Execute: Use the Bundled Script

The entire pipeline is handled by scripts/validate_phones.py. Always run this script rather than reimplementing the API calls — it handles rate limiting, error recovery, progress reporting, and the exact CSV format DataSift expects.

Step 1: Install Prerequisites

pip install --break-system-packages requests

No other dependencies are needed.

Step 2: Get the User's Trestle API Key

The script requires a Trestle API key. Check for it in this order:

1. Environment variable: TRESTLE_API_KEY
2. Ask the user to provide it

If the user doesn't have one, direct them to https://trestleiq.com to sign up — they get 25 free queries per product on their trial.

Step 3: Estimate Cost & Get User Confirmation

This step is mandatory. Before making any API calls, always run the script in estimate mode first. This parses the CSV, counts unique phone numbers across all columns, deduplicates, and calculates the cost at $0.015 per phone.

python3 SKILL_DIR/scripts/validate_phones.py \
  --input "path/to/phones.csv" \
  --estimate

This will output something like:

==================================================
  PHONE VALIDATION COST ESTIMATE
==================================================
  Input file:          Phone Enrichment.csv
  Total phone entries: 9,648
  Unique phones:       3,865
  Duplicates saved:    5,783
  Cost per phone:      $0.015
  ─────────────────────────────────────
  ESTIMATED COST:      $57.98
==================================================

Present this to the user and wait for their explicit confirmation before proceeding. The deduplication savings are worth calling out — in a typical DataSift export, the same person (and their phones) can appear on multiple rows because they own multiple properties. The script only charges once per unique phone number.

For programmatic use, --estimate-json returns the same data as a JSON object.

Step 4: Run the Validation

Once the user confirms the cost, run the full validation:

python3 SKILL_DIR/scripts/validate_phones.py \
  --input "path/to/phones.csv" \
  --output "path/to/output_directory/" \
  --api-key "$TRESTLE_API_KEY"

Replace SKILL_DIR with the actual path to this skill's directory.

Optional flags:

Step 5: Understand the Output

The script produces these files in the output directory:

1. phone_tags_for_datasift.csv — The primary output. Two columns:

   • Phone Number — cleaned 10-digit phone number
   • Phone Tag — the assigned tier tag

   This is the file users upload to DataSift. They go to Upload → Update Data → "Tag phones by phone number", map the two columns, and the tags propagate across all records sharing that phone number.

2. validation_results.csv — Detailed results with all API data:

   • phone_number — the queried number
   • activity_score — 0-100 score from Trestle
   • line_type — Mobile, Landline, FixedVOIP, NonFixedVOIP, Tollfree, etc.
   • carrier — carrier name
   • is_valid — whether the number is a valid format
   • is_prepaid — prepaid indicator
   • assigned_tag — the tier tag assigned
   • is_litigator_risk — (if --add-litigator was used)

3. summary.txt — Human-readable summary with counts per tier, score distribution, and line type breakdown.

4. validation_report.xlsx — (if --full-report) Excel workbook with formatted tables, charts for score distribution, and tier breakdowns.

Input Format: DataSift Phone Enrichment Export

The script is built to work directly with DataSift's "Phone Enrichment" CSV export format. This is a wide-format file where each record (property/contact) can have up to 30 phone numbers, each with associated metadata columns:

Phone 1, Phone Type 1, Phone Status 1, Phone Tags 1, Phone Is Connected 1,
Phone 2, Phone Type 2, Phone Status 2, Phone Tags 2, Phone Is Connected 2,
...
Phone 30, Phone Type 30, Phone Status 30, Phone Tags 30, Phone Is Connected 30

The script automatically detects all Phone N columns (1-30) and ignores the metadata columns (Phone Type N, Phone Status N, Phone Tags N, Phone Is Connected N). It then extracts every phone number across all columns and rows, deduplicates them, and sends only unique numbers to the API.

The existing Phone Type values from skip tracing (MOBILE, LANDLINE, etc.) are left untouched — this skill only adds phone tags, it does not modify the type or status fields.

The script also works with simpler CSV formats that just have a Phone or Phone Number column.

Tier Strategy

Default (5 Tiers)

Five priority buckets that give callers a clear work order without overcomplicating things. Based on analysis of validated phone numbers against actual Sift call outcomes:

This gives callers a clear work order: burn through Dial First, move to Dial Second, then Dial Third, and reach into Dial Fourth if there's still time on the clock. Drop gets excluded entirely.

Custom Tiers

If you need different boundaries or tag names, pass a JSON object mapping tag names to score ranges:

--custom-tiers '{"Priority": [80, 100], "Standard": [50, 79], "Low": [20, 49], "Remove": [0, 19]}'

Line Type Context

The Trestle API returns these line types, which matter for how you contact the number:

A key insight from our research: 24% of numbers that Sift labels as "Landline" are actually FixedVOIP or NonFixedVOIP when checked against Trestle. These are textable numbers being miscategorized — the detailed validation_results.csv output surfaces this with the line_type column so you can identify which "Landline" numbers are actually textable.

DataSift Upload Workflow

After the script generates phone_tags_for_datasift.csv:

1. Log into your DataSift/REISift account
2. Go to Upload → select Update Data
3. Choose "Tag phones by phone number"
4. Upload the CSV file
5. Map Phone Number → Phone Number field
6. Map Phone Tag → Phone Tag field
7. Complete the upload

The tags will apply across ALL records that share each phone number. So if the same number appears on 3 different property records, all 3 get the tag.

Integration / Dialer Workflow

Once tagged, when sending to a dialer integration:

• Go to Send To → select your dialer
• Under phone tag filters, select the tier(s) you want to send
• Important: Each transfer should only include ONE phone tag tier, because the filter requires the number to have ALL selected tags. Send "Dial First" separately from "Dial Second", etc.

For non-integrated dialers, use Export → filter by the specific phone tag.

Handling Edge Cases

Duplicate phone numbers: The script deduplicates before calling the API to avoid wasting queries. Each unique number is scored once, and the tag CSV includes one row per unique number. In a typical DataSift export, the same owner's phones repeat across multiple property rows — dedup catches all of these.

Invalid/short numbers: Numbers that fail Trestle's is_valid check get tagged as "Invalid" and excluded from the tier tagging.

API errors / timeouts: The script retries failed requests up to 3 times with exponential backoff. Permanently failed numbers are logged to errors.csv.

Numbers already tagged in Sift: Uploading new tags via "Update Data" ADDS to existing tags — it does not replace them. If you need to remove old tags first, you'd do a separate "Remove phone tags by phone number" upload.

Large lists: Trestle rate-limits API calls. The script defaults to 10 concurrent requests with 100ms delay between batches. For lists over 10,000 numbers, consider using Trestle's batch upload product instead.

No API key available: If the user doesn't have a Trestle API key and can't get one, the script can run in --dry-run mode which generates the CSV template with placeholder tags so they can see the format and manually fill in scores later.