Skip to main content
POST
/
v1.5
/
GeoScrub
/
IsTimeLegalToCall
Returns a boolean true or false if a phone number call is permitted on a provided datetime. If the call is permitted, also provides number of seconds remaining in legal calling window.
curl --request POST \
  --url https://dataapi.dncscrub.com/v1.5/GeoScrub/IsTimeLegalToCall \
  --header 'Content-Type: application/json' \
  --data '
{
  "IsTimeLegalToCall": [
    {
      "PhoneNumber": "<string>",
      "CallProposedDateTimeInUTC": "2023-11-07T05:31:56Z",
      "DNCProjId": "<string>"
    }
  ]
}
'
[
  {
    "Response": [
      {
        "PhoneNumber": "<string>",
        "IsCallPermitted": true,
        "SecondsInCallWindow": 123
      }
    ]
  }
]

​
Request Parameters

ParameterTypeRequiredDescription
PhoneNumberstringYesThe phone number to check
CallProposedDateTimeInUTCdatetimeNoThe proposed call time in UTC. Defaults to current UTC time if not provided or null.
DNCProjIdstringNoDNCScrub project ID for custom calling hours. If provided, must be a valid project accessible by your account.
The CallProposedDateTimeInUTC parameter is optional. If omitted or set to null, the API will use the current UTC time, making it easy to check if a call is legal right now without having to calculate the current time yourself.

​
How calling windows are determined

IsCallPermitted is true when the proposed time falls inside one of the legal calling windows for the called party’s local time. Windows are resolved in priority order:
  1. Project-level override — calling-hour rules you’ve configured against your DNCProjId for a given state in the DNCScrub Portal. Use this when your brand wants stricter rules than law requires.
  2. State law overlay — state-specific telephone solicitation curfews tracked by Contact Center Compliance. For example, Alabama is 8 AM – 8 PM with no Sunday calls; California is 9 AM – 9 PM all 7 days; Florida is 8 AM – 8 PM. State laws are maintained by our in-house compliance counsel and updated as legislation changes — no client-side change is required.
  3. Federal baseline — applied when no state overlay exists. US numbers default to FCC TCPA: 8 AM – 9 PM, all 7 days, called-party local time. Canadian numbers default to CRTC: 9 AM – 9:30 PM weekdays, 10 AM – 6 PM weekends.
A state with no Sunday calling allowed (e.g. AL/LA/MS) returns IsCallPermitted = false for any Sunday timestamp.
The response reflects residential telephone solicitation curfews. B2B calls have different rules in some states (full exemptions, narrower windows, etc.) — this API does not apply B2B exemptions. If your call list is exclusively to businesses, apply that logic on your side.

​
Response Fields

Every input phone produces exactly one row in the response. Inspect Status to decide how to handle each row.
FieldTypeDescription
PhoneNumberstringThe 10-digit phone number the row applies to
IsCallPermittedbooleantrue only when Status is "OK" and the proposed call time falls within a legal calling window. Always false for any non-OK status, so dialers that ignore Status still fail closed.
SecondsInCallWindowintegerSeconds remaining in the legal calling window after the proposed time. Meaningful only when IsCallPermitted is true
StatusstringOutcome code for the row. See the table below
StatusMessagestringHuman-readable explanation when Status is not "OK". null when Status is "OK"

​
Status Values

StatusMeaningRecommended client action
OKRow processed successfully. IsCallPermitted and SecondsInCallWindow are valid.Use the result.
INVALID_PHONEPhone number failed format validation (not 10 digits, not numeric, etc.).Skip; flag the source list for cleanup.
INVALID_PROJECTThe DNCProjId on the row is unknown or not accessible by your account.Verify the project id; skip the row.
INVALID_DATECallProposedDateTimeInUTC is outside the supported range (more than 50 years from today).Verify the date; skip the row.
TOLL_FREEPhone is in a toll-free NANP area code (8YY: 800, 833, 844, 855, 866, 877, 888 today; future-reserved 822/880-884/886/887/889 also blocked). Non-geographic, so legal call times cannot be determined.Skip; do not retry. Filter from source list.
UNKNOWN_NXXThe NPA-NXX is not in our prefix master list. Because the master list is refreshed from definitive telco data, this almost always means the NXX is unassigned/invalid (a number that does not ring anyone).Skip; flag the source list for cleanup.
We deliberately do not guess a timezone for UNKNOWN_NXX numbers: a wrong “legal to call” answer driven by a guessed timezone is TCPA exposure, and silently approving calls to nonworking numbers would hide data quality problems on your side.
Per-row Status replaces the older behavior where a single bad phone caused the entire batch to return HTTP 400. The endpoint now returns 200 with one row per input phone; inspect Status to decide which rows are usable. HTTP 400 is still returned for batch-level errors (missing body, empty list, more than 1000 phones).

Headers

​
loginId
string

LoginId (aka APIKey)

Body

​
IsTimeLegalToCall
object[] | null

Response

Success

​
Response
object[] | null