Bulk Phone Validator & FCC Complaint Risk Checker

Normalize bulk phone lists, check public government unwanted-call complaint history without API keys, optionally add live carrier data, and produce CRM-ready ALLOW, REVIEW, or SUPPRESS decisions for SMS and voice.

The default open-risk mode is immediately usable. It combines:

• E.164, national, and international formatting
• Numbering-plan validity and approximate line type
• Public FCC unwanted-call complaint counts, recency, call types, and a transparent risk score
• Consent, internal opt-out, and campaign-context policy
• Duplicate-aware lookups with one output row per CRM record
• Flat CSV-ready exports with stable reason and warning codes

Government complaint records are consumer-submitted and unverified. Caller ID may have been spoofed. They are not National Do Not Call Registry registrations and never trigger automatic suppression by themselves.

Enrichment modes

Mode	Credentials	Coverage
open-risk	None	Formatting, numbering metadata, and FCC complaint history for NANP numbers
live-carrier	Telnyx key	Open-risk coverage plus current carrier, portability, LRN, OCN, and provider line type
offline	None	Formatting and numbering-plan metadata only

Optional bring-your-own-provider integrations are available. IPQS adds provider-specific fraud, activity, reputation, DNC, and TCPA-risk fields; those fields are provider signals, not direct access to the official National Do Not Call Registry. Twilio can check US number reassignment when the account is approved and the source row contains a consent verification date.

Quick start

No credentials are required for the default mode:

{
  "phoneNumbers": [
    "+14155552671",
    "+442079460958",
    "bad-number"
  ],
  "campaignType": "manual",
  "intendedChannel": "both",
  "enrichmentMode": "open-risk"
}

Input

Choose exactly one source:

1. phoneNumbers: a quick list of strings.
2. records: JSON CRM records.
3. sourceDatasetId: an existing Apify dataset.
4. sourceUrl: CSV, JSON, or JSONL over HTTPS.

Example no-key CRM run:

{
  "records": [
    {
      "lead_id": "crm-1042",
      "mobile": "(415) 555-2671",
      "sms_consent": "granted",
      "consent_verified_at": "2026-02-14",
      "unsubscribed": false,
      "owner": "west-team"
    }
  ],
  "phoneField": "mobile",
  "idField": "lead_id",
  "consentStatusField": "sms_consent",
  "consentDateField": "consent_verified_at",
  "optOutField": "unsubscribed",
  "passThroughFields": ["owner"],
  "campaignType": "marketing",
  "intendedChannel": "both",
  "enrichmentMode": "open-risk"
}

Dotted mappings such as contact.phone and compliance.consent.status are supported.

Output

Every input row is retained, including duplicates. Paid or remote lookups are deduplicated by E.164 number within a run.

Group	Important fields
Identity	source_id, phone_raw, phone_e164, country_code
Format	format_valid, format_possible, formatted variants, metadata_line_type
Complaint risk	government_complaint_match, government_complaint_count, government_complaint_last_date, government_complaint_call_types, government_complaint_risk_score
Carrier	carrier_name, carrier_line_type, carrier_source, carrier_data_kind, portability fields
Reachability	active, active_status, sms_capability_estimate, sms_deliverable
Optional provider risk	fraud_score, provider_spam_flag, provider_dnc_match, provider_tcpa_risk_match
Workflow	decision, sms_decision, voice_decision, recommended_channel, reason and warning codes
Audit	providers_checked, lookup_status, checked_at, provider_errors

sms_capability_estimate=likely means the numbering metadata or live provider classified the line as mobile. It is not proof that an SMS will be delivered. The Actor does not send a test message, so sms_deliverable is currently always null.

Complaint risk score

The Actor aggregates exact-number FCC complaint history and calculates a 0-100 score from complaint volume and recency. The method is deterministic and intentionally conservative:

• No complaint match produces score 0.
• Recent and repeated reports increase the score.
• Older reports decay substantially.
• Scores at or above complaintReviewThreshold default to REVIEW.
• Complaint history alone never produces SUPPRESS.

The output includes UNVERIFIED_GOVERNMENT_COMPLAINT_HISTORY and CALLER_ID_MAY_HAVE_BEEN_SPOOFED whenever a match is found.

Decision policy

• Invalid numbers, internal opt-outs, denied consent, confirmed inactive lines, provider DNC/TCPA-risk matches, and confirmed reassignment can suppress a row.
• Missing marketing consent, elevated complaint risk, provider failures, VoIP SMS, landline SMS, and elevated provider fraud risk go to review.
• Unknown live activity is a warning by default, because the open-risk tier does not claim to test reachability.
• SMS and voice decisions are evaluated separately.

ALLOW means no configured rule blocked or escalated the row. It is not a determination that contacting the number is lawful. Users remain responsible for consent, purpose, jurisdiction, calling method, official DNC access, and their own suppression lists.

Data sources and limitations

• FCC Consumer Complaints - Unwanted Calls: public, consumer-submitted complaint history. The FCC does not verify the allegations.
• libphonenumber-js: formatting and numbering-plan metadata derived from Google's libphonenumber metadata. It does not confirm assignment, reachability, or the current carrier after porting.
• Telnyx Number Lookup: optional current carrier and portability enrichment.
• IPQualityScore: optional BYO provider risk signals.
• Twilio Reassigned Number: optional BYO US reassignment check requiring approval.

FCC coverage is currently queried for +1 NANP numbers. Other countries still receive global formatting and numbering-plan metadata, with complaint coverage marked unavailable or not applicable.

In open-risk and live-carrier modes, eligible numbers are sent to the FCC Socrata open-data endpoint in batched exact-match queries. Use offline mode or disable checkGovernmentComplaints when that external disclosure is not appropriate for the input data.

Pricing

• Actor start: $0.005 per run.
• Open-risk mode: $1.00 per 1,000 unique valid phone numbers.
• Live-carrier mode: $2.00 per 1,000 unique valid phone numbers.
• Offline mode: no per-number charge.

Invalid numbers are not charged per phone. Duplicate numbers share one lookup and per-phone charge while every source row remains in the output. BYO providers may bill their API usage separately. The pricing panel on the Actor page is the authoritative current price.

Limits and privacy

• sourceUrl downloads are capped at 50 MB.
• maxRecords defaults to 100,000.
• Provider requests use bounded retries.
• Phone numbers and source records are personal data. Configure retention and access accordingly.