Skip to main content
GET
Scrub Single Number
Scrub a single phone number against all configured DNC lists and compliance databases.

Request

Headers

string
required
Your API Key

Query Parameters

string
required
The 10-digit phone number to scrub. Optionally append a pipe-delimited identifier (5039367181|ACCT-1) and/or postal code (5039367181|ACCT-1|10001; leave the identifier empty to pass only a postal code: 5039367181||10001) — see Postal Code Time Zones
string
default:"8"
required
API version. Use 8 (latest). Version 6 adds EBRExpiresOn; version 7 adds WirelessPortDate and VoIPDate; version 8 adds PostalCode, TZSource, IsCallAllowedNonATDS, IsCallAllowedATDS and IsCallAllowedAI, and returns JSON as a typed object ({"version": 8, "results": [...]}) instead of an array of strings — see JSON response shape.
string
default:"json"
Response format: json or csv
string
Optional. Project ID
string
Optional. Campaign ID

Postal Code Time Zones

By default TZCode, UTCOffset, CallingWindow, CallingTimeRestrictions and DoNotCallToday are derived from the phone number’s area code and prefix. Mobile numbers keep their area code when their owner moves, so the area code is not always where the person is. If you know the contact’s postal code, pass it and those fields are calculated from the postal code’s time zone and state instead — state calling hours, state holidays and state-of-emergency blocks all follow the postal code’s state. The postal code is always passed per number, as the third pipe-delimited field of phoneList: PHONE|ID|POSTALCODE. Leave the ID empty if you don’t use one:
There is deliberately no request-level parameter — one postal code applied to a whole list would silently mis-time every other number. See Unique Identifiers for the pipe syntax. Accepted formats: 5-digit US ZIP (ZIP+4 is accepted, e.g. 10001-1234; only the first five digits are used) and Canadian postal codes (M5V3L9, or just the M5V forward sortation area). Case and hyphens are ignored. Do not put spaces inside a phoneList entry — whitespace separates phone numbers, so M5V 3L9 must be sent as M5V3L9 (or M5V-3L9). If the postal code is not recognized, the number is processed exactly as if no postal code had been passed. Use version=8 to receive TZSource, which tells you which method was used.
The postal code only affects the time zone and calling-window fields. ResultCode, Reason, RegionAbbrev, Country, Locale, DNC list matching and EBR logic are always based on the phone number.

One-Field Answer

With version=8 the response also includes three yes/no flags so you don’t have to interpret ResultCode, EBRType, DoNotCallToday and the calling window yourself. Pick the one that matches how you place calls: See Is the call allowed? for the rules and Compliance for AI Voice Agents for the AI workflow end to end.

Example Request

Response Fields

string
The phone number that was scrubbed
string
The scrub result code (see Result Codes)
string | null
Your unique identifier if you passed one (PHONE|ID), otherwise null
string
Explanation of why the number is flagged
string
State/region abbreviation (e.g., “CA”)
string
Two-digit country code (e.g., “US”)
string
City or locality
string
Carrier information in format: ID;TYPE;"Name"
string | null
New area code if the number’s area code has been split or overlaid, otherwise null
integer
Time zone code (see Timezone Codes). Derived from the postal code when one is supplied, otherwise from the area code
string | null
Permitted calling hours in the destination’s local time, HH:MM-HH:MM, as three semicolon-separated windows: weekday;Saturday;Sunday (e.g. 8:00-21:00;8:00-21:00;8:00-21:00). null when no window applies
integer
UTC offset in minutes for the destination, adjusted for DST (e.g. -240)
boolean
true if the number should not be called today (state holiday or state of emergency)
integer
Bit field: 1 = it is currently outside the calling window, 2 = an EBR exemption to the calling window is available, 4 = the destination state does not specify its own calling window (or you are exempt from it), so the federal 8 AM–9 PM window applies
string | null
Type of EBR applied: S (Sale), I (Inquiry), or P (Permission). null if no EBR
boolean
true if wireless or VoIP
string
Line type: Wireless, VoIP, or AllOther
string | null
Date the EBR expires, YYYY-MM-DD (e.g. 2027-02-09), inclusive — the number may be called through the end of that day in the destination’s local time. The earlier of the federal and state expiration dates. null if no EBR. Requires version=6 or higher (versions 6–7 return YYYY-MM-DD 23:59:00 as a string)
string | null
Date the number was ported to wireless, YYYY-MM-DD. null when there is no port record (versions 7 returns 0 or empty). Requires version=7 or higher
string | null
Date the number was identified as VoIP, YYYY-MM-DD. null if not VoIP. Requires version=7 or higher
string | null
Normalized postal code used for the time zone calculation (10001, M5V). null if none was supplied. Requires version=8 or higher
string
postalCode when the time zone and calling window were derived from the supplied postal code, otherwise areaCode. Requires version=8 or higher
boolean
true if a manually dialed, live-agent marketing call may be placed to this number right now. Combines ResultCode, DoNotCallToday and the calling window. See Is the call allowed? for the rules and for when this flag applies to you. Requires version=8 or higher
boolean
Same checks, for calls placed by an autodialer (federal or state definition). Wireless and VoIP numbers return false unless a Permission (P) EBR — express written consent — is on file. Requires version=8 or higher
boolean
Same checks, for calls using an artificial, prerecorded or AI-generated voice. true only when a Permission (P) EBR is on file and still valid (EBRType is P and ResultCode is E, O, G or H) — any line type. Clean numbers without consent return false. See Compliance for AI Voice Agents. Requires version=8 or higher

Handling the Response. Make sure to handle all response codes. The sample below handles just a few