Legal Call Times for Date

Get the legal calling windows for a phone number on a specific date

POST /v1.5/GeoScrub/LegalCallTimesForDate

Provides the times in UTC that a telephone call can be placed for a given phone and date

cURL

curl --request POST \
  --url https://dataapi.dncscrub.com/v1.5/GeoScrub/LegalCallTimesForDate \
  --header 'Content-Type: application/json' \
  --data '
{
  "LegalCallTimesForDate": [
    {
      "PhoneNumber": "<string>",
      "Date": "2023-11-07T05:31:56Z",
      "DNCProjId": "<string>",
      "NumberOfDays": 123
    }
  ]
}
'

200

[
  {
    "LegalCallTimes": [
      {
        "PhoneNumber": "<string>",
        "ValidTimesInUTC": [
          {
            "StartInUTC": "2023-11-07T05:31:56Z",
            "EndInUTC": "2023-11-07T05:31:56Z"
          }
        ]
      }
    ]
  }
]

How calling windows are determined

The endpoint returns the legal calling windows for the called party’s local time, applying these rules 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 row with 00:00–00:00 for a given day means no calling allowed that day (e.g. Alabama, Louisiana, Mississippi forbid Sunday telephone solicitations). The response will include zero windows for that day.

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 entry in LegalCallTimes. Inspect Status to decide how to handle each row.

Field	Type	Description
PhoneNumber	string	The 10-digit phone number the row applies to
ValidTimesInUTC	array	List of { StartInUTC, EndInUTC } windows during which the number can legally be called. Empty array for any non-OK status, so dialers that ignore Status still fail closed.
Status	string	Outcome code for the row. See the table below
StatusMessage	string	Human-readable explanation when Status is not "OK". null when Status is "OK"

Status Values

Status	Meaning	Recommended client action
OK	Row processed successfully. ValidTimesInUTC lists the legal call windows.	Use the result.
INVALID_PHONE	Phone number failed format validation.	Skip; flag the source list for cleanup.
INVALID_PROJECT	The DNCProjId on the row is unknown or not accessible by your account.	Verify the project id; skip the row.
INVALID_DATE	Date is outside the supported range or contains a time component.	Verify the date; skip the row.
TOLL_FREE	Phone is in a toll-free NANP area code (8YY). Non-geographic.	Skip; do not retry. Filter from source list.
UNKNOWN_NXX	The 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.	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

application/jsontext/jsonapplication/*+json

LegalCallTimesForDate · object[] | null

Show child attributes

Response

200

application/json

Success

LegalCallTimes · object[] | null

Show child attributes