> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dncscrub.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Is Time Legal to Call
> Check if a call is permitted at a specific date and time
## Request Parameters
| Parameter | Type | Required | Description |
| --------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `PhoneNumber` | string | Yes | The phone number to check |
| `CallProposedDateTimeInUTC` | datetime | No | The proposed call time in UTC. **Defaults to current UTC time if not provided or null.** |
| `DNCProjId` | string | No | DNCScrub 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.
| Field | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PhoneNumber` | string | The 10-digit phone number the row applies to |
| `IsCallPermitted` | boolean | `true` 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.** |
| `SecondsInCallWindow` | integer | Seconds remaining in the legal calling window after the proposed time. Meaningful only when `IsCallPermitted` is `true` |
| `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. `IsCallPermitted` and `SecondsInCallWindow` are valid. | Use the result. |
| `INVALID_PHONE` | Phone number failed format validation (not 10 digits, not numeric, etc.). | 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` | `CallProposedDateTimeInUTC` is outside the supported range (more than 50 years from today). | Verify the date; skip the row. |
| `TOLL_FREE` | Phone 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_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 (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).
## OpenAPI
````yaml POST /v1.5/GeoScrub/IsTimeLegalToCall
openapi: 3.0.1
info:
title: DNCScrub APIs at dataapi.dncscrub.com
version: '1.5'
servers:
- url: https://dataapi.dncscrub.com
security:
- LoginId: []
paths:
/v1.5/GeoScrub/IsTimeLegalToCall:
post:
tags:
- GeoScrub
summary: "Returns a boolean true or false if a phone number call is permitted\r\non a provided datetime. If the call is permitted, also provides\r\nnumber of seconds remaining in legal calling window."
parameters:
- name: loginId
in: header
description: LoginId (aka APIKey)
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/IsTimeLegalToCallRequestDTO'
text/json:
schema:
$ref: '#/components/schemas/IsTimeLegalToCallRequestDTO'
application/*+json:
schema:
$ref: '#/components/schemas/IsTimeLegalToCallRequestDTO'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IsTimeLegalToCallResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ReasonPhraseError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ReasonPhraseError'
security: []
components:
schemas:
IsTimeLegalToCallRequestDTO:
type: object
properties:
IsTimeLegalToCall:
type: array
items:
$ref: '#/components/schemas/IsTimeLegalToCallDTO'
nullable: true
additionalProperties: false
IsTimeLegalToCallResponseDTO:
type: object
properties:
Response:
type: array
items:
$ref: '#/components/schemas/IsTimeLegalToCall'
nullable: true
additionalProperties: false
ReasonPhraseError:
type: object
properties:
ReasonPhrase:
type: string
description: Description of the error
nullable: true
additionalProperties: false
IsTimeLegalToCallDTO:
type: object
properties:
PhoneNumber:
type: string
nullable: true
CallProposedDateTimeInUTC:
type: string
format: date-time
nullable: true
description: >-
Optional. If omitted or set to null, defaults to the current UTC
time.
DNCProjId:
type: string
nullable: true
additionalProperties: false
IsTimeLegalToCall:
type: object
properties:
PhoneNumber:
type: string
nullable: true
IsCallPermitted:
type: boolean
SecondsInCallWindow:
type: integer
format: int32
additionalProperties: false
securitySchemes:
LoginId:
type: apiKey
description: >-
LoginId Authentication: Authenticate using the LoginId generated from
DNCScrub User Manager. In HTTP header place "loginId: {loginId}"
name: loginId
in: header
````