ACTION_ID: person_phone_number_verification_using_real_phone
NAME: Real Phone : Phone Number Verification
CATEGORY: enrich
CREDITS: 2

Verify a North American (US or Canadian) phone number for dialer
compliance — returns call status plus National DNC, State DNC, DMA,
litigator, and IsCell flags so you can filter unsafe-to-dial
numbers before sending to your dialer.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

phone_number (type: string, required) — Phone Number
  North American phone number to verify (US or Canada). The backend
  normalizes most common formats — pass any of these and the action
  will handle it:
    "+16475629957"     E.164 with country code
    "1-647-562-9957"   country-code + dashes
    "(647) 562-9957"   parenthesized area code
    "9258675309"       bare 10 digits
  Don't pre-process with a JS formatter just to strip the `+1` or
  separators — normalization is handled server-side.

================================================================================
2. OUTPUTS
================================================================================

phone_verification_status (type: string) — Phone Verification Status
  Overall verification status returned by RealPhone for this
  number.

response_code (type: string) — Response Code
  Provider response code (status of the verification call).

response_message (type: raw_array) — Response Message
  Provider response message body — nested JSON with verification
  detail.

national_dnc (type: string) — National DNC
  National Do-Not-Call registry status for the number.

state_dnc (type: string) — State DNC
  State-level Do-Not-Call registry status for the number.

dma (type: string) — DMA
  DMA (Direct Marketing Association) status for the number.

litigator (type: string) — Litigator
  Known-litigator flag — whether this number is associated with
  a serial-litigator profile.

iscell (type: string) — IsCell
  Mobile / cellular indicator — whether the number is a cell
  phone vs landline.

id (type: string) — Id
  RealPhone's record ID for the verification.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Configure Action body:

{
  "inputs": {
    "phone_number": "{{input.phone_number}}"
  }
}

Pass any North American phone number (US or Canada). Country code,
parentheses, dashes, spaces are all fine — the action normalizes
server-side. A common upstream is
`personal_phone_number_by_linkedin_url_waterfall`, which emits
E.164 like `+16475629957`; pipe its output directly into this
action without an intermediate JS normalizer.

================================================================================
4. KEY NOTES
================================================================================

- North American only — US and Canadian numbers are accepted; the
  backend handles country-code normalization and accepts the common
  surface forms (`+1...`, `1-...`, `(xxx) xxx-xxxx`, bare 10 digits).
- Compliance fields (`national_dnc`, `state_dnc`, `dma`, `litigator`)
  validate against US registries — National DNC, State DNC, DMA,
  and the US national litigator list. Canadian numbers will return
  these fields populated but the "N" values reflect the US-registry
  perspective; for Canadian dialing compliance (CRTC's National
  Do Not Call List), verify separately.
- `iscell` (mobile / landline indicator) works for both US and
  Canadian numbers — useful for splitting SMS-eligible numbers
  from voice-only.
- Filter on `national_dnc`, `state_dnc`, `dma`, and `litigator`
  before sending to a US dialer to avoid TCPA / DNC violations.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: phone enrichment -> person_phone_number_verification_using_real_phone -> dialer.

================================================================================
6. WHEN TO USE
================================================================================

Use person_phone_number_verification_using_real_phone for
compliance-aware North American dialer hygiene. Run this on
numbers you've already enriched, before sending them to a dialer
or SMS sender. The DNC / DMA / litigator flags are US-registry
checks; the iscell flag and call-status response work for both
US and Canadian numbers.

================================================================================
7. WHEN NOT TO USE
================================================================================

Looking for a person's phone number (vs verifying one you already have)
  -> personal_phone_number_by_linkedin_url_waterfall
     (https://floqer.com/docs/action-detail/personal_phone_number_by_linkedin_url_waterfall.txt)

Non-North-American phone numbers — the action accepts US and
Canadian numbers; numbers from other regions are out of scope and
will not return meaningful flags.

================================================================================

This file is maintained manually. Last updated: 2026-05-14.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt