is_time_legal_to_call Tool - Contact Center Compliance

The is_time_legal_to_call tool checks if it is currently legal to call a phone number based on the recipient’s local time and state regulations. Use this for real-time call decisions.

When to Use

Before initiating an outbound call
Real-time compliance checking in dialers
Voice AI pre-call screening

Parameters

array

required

Array of objects containing phone numbers and proposed call times.

Show phoneNumber object

string

required

10-digit North American phone number (e.g., "5039367187").

string

ISO 8601 datetime in UTC when you want to call (e.g., "2024-01-15T14:30:00Z"). Optional - defaults to current UTC time if not provided.

string

Optional DNCScrub project ID for custom calling hours.

API key. Only required if not provided via the x-dncscrub-api-key HTTP header.

Response

boolean

Whether the API call succeeded.

array

Array of results, one per phone number.

Show result object

string

The phone number checked.

boolean

true if calling is legal at the proposed time.

number

Seconds remaining in legal calling window (0 if not permitted).

number

Minutes remaining in legal calling window for convenience.

string

Machine-readable error code (when failed).

string

Human-readable error description (when failed).

Examples

Request
Permitted
Not Permitted

{
  "phoneNumbers": [
    {
      "phoneNumber": "5039367187",
      "callProposedDateTimeInUTC": "2024-01-15T18:30:00Z"
    }
  ]
}

{
  "success": true,
  "results": [
    {
      "phone": "5039367187",
      "isCallPermitted": true,
      "secondsRemaining": 7200,
      "minutesRemaining": 120
    }
  ]
}

{
  "success": true,
  "results": [
    {
      "phone": "5039367187",
      "isCallPermitted": false,
      "secondsRemaining": 0,
      "minutesRemaining": 0
    }
  ]
}

Usage Notes

The callProposedDateTimeInUTC parameter is optional - if omitted, it defaults to the current UTC time
secondsRemaining tells you how long you have before the calling window closes
Different states have different calling hour restrictions
Some states have additional restrictions on Sundays and holidays
For planning future calls, use get_legal_call_times instead

​When to Use

​Parameters

​Response

​Examples

​Usage Notes

When to Use

Parameters

Response

Examples

Usage Notes