> ## 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.
# Legal Call Times for Date
> Get the legal calling windows for a phone number on a specific date
## 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).
## OpenAPI
````yaml POST /v1.5/GeoScrub/LegalCallTimesForDate
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/LegalCallTimesForDate:
post:
tags:
- GeoScrub
summary: "Provides the times in UTC that a telephone call can be placed\r\nfor a given phone and date"
parameters:
- name: loginId
in: header
description: LoginId (aka APIKey)
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/LegalCallTimesForDateRequestDTO'
text/json:
schema:
$ref: '#/components/schemas/LegalCallTimesForDateRequestDTO'
application/*+json:
schema:
$ref: '#/components/schemas/LegalCallTimesForDateRequestDTO'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LegalCallTimesForDateResponseDTO'
'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:
LegalCallTimesForDateRequestDTO:
type: object
properties:
LegalCallTimesForDate:
type: array
items:
$ref: '#/components/schemas/LegalCallTimesForDateDTO'
nullable: true
additionalProperties: false
LegalCallTimesForDateResponseDTO:
type: object
properties:
LegalCallTimes:
type: array
items:
$ref: '#/components/schemas/LegalCallTimesForPhoneDTO'
nullable: true
additionalProperties: false
ReasonPhraseError:
type: object
properties:
ReasonPhrase:
type: string
description: Description of the error
nullable: true
additionalProperties: false
LegalCallTimesForDateDTO:
type: object
properties:
PhoneNumber:
type: string
nullable: true
Date:
type: string
format: date-time
DNCProjId:
type: string
nullable: true
NumberOfDays:
type: integer
format: int32
nullable: true
additionalProperties: false
LegalCallTimesForPhoneDTO:
type: object
properties:
PhoneNumber:
type: string
nullable: true
ValidTimesInUTC:
type: array
items:
$ref: '#/components/schemas/CallTimeWindowDTO'
nullable: true
additionalProperties: false
CallTimeWindowDTO:
type: object
properties:
StartInUTC:
type: string
format: date-time
EndInUTC:
type: string
format: date-time
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
````