Phone safety flags, connect grades, and which mobiles are billed
What the dnc flags, connect_grade, and tcpa_notice on every phone result mean, and when a mobile is free.
Every phone result, from POST /v1/phones/lookup, mobile in /v1/people/enrich, or the lookup_phone and enrich_person MCP tools, includes:
line_typeandcarrierfrom a live carrier check.dnc:federal(National Do Not Call Registry),state(state lists), andreassigned(disconnected since your consent date), eachtrue,false, ornullwhen not checked.dnc.statussayschecked,partial, ornot_checked, anddnc.noteexplains any null. We never fill in a flag we didn't check.connect_gradefrom A to D: A is a mobile line not reassigned since your consent date, B is a mobile line we couldn't check for reassignment, C means the line type is unknown, and D is VoIP. It's about reaching the person, not permission to call.tcpa_notice: WhoLayer never calls or texts anyone, and calling or texting needs the consent the TCPA and state laws require.
Reassigned numbers
Send consent_date (YYYY-MM-DD), the day you got the person's consent or last verified the number. When the reassigned-number check is switched on, we check whether the number was disconnected since then. A reassigned number is withheld and you aren't charged.
Which mobiles are billed
You pay 5 credits only for a connectable mobile:
- Landlines and invalid numbers are never returned or charged.
- Reassigned numbers are withheld and not charged.
- VoIP numbers come back free (
billed: false) while your workspace's free allowance lasts. It grows with the mobiles you're billed for over the last 30 days. Past that, VoIP is charged like a mobile.
Before you call
These flags help, but they don't grant permission. Get consent where the law requires it, honor Do-Not-Call lists and your own opt-outs, and don't use autodialed or prerecorded calls or texts without consent. A null flag means "not checked", not "OK to call".
Try it with a test key
Test keys return fictional numbers. Put sandbox-voip, sandbox-landline, sandbox-reassigned (with a consent_date), or sandbox-dnc in the name or email you send to see each case.