get_legal_call_times Tool - Contact Center Compliance

The get_legal_call_times tool returns the legal calling windows (start and end times in UTC) for phone numbers on a given date. Use this to schedule calls in advance or display available calling times to agents.

When to Use

Planning call schedules for future dates
Displaying legal calling windows to agents
Building call queues with time-aware scheduling

Parameters

array

required

Array of objects containing phone numbers and dates.

Show phoneNumber object

string

required

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

string

required

ISO 8601 date for which to get legal calling times (e.g., "2024-01-15").

string

Optional DNCScrub project ID for custom calling hours.

number

Number of days to return (defaults to 1).

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.

array

Array of legal calling time windows.

Show window object

string

Start of legal calling window in UTC.

string

End of legal calling window in UTC.

boolean

true if there is at least one legal window to call.

string

Machine-readable error code (when failed).

string

Human-readable error description (when failed).

Examples

Request
Response
No Window (Holiday)

{
  "phoneNumbers": [
    {
      "phoneNumber": "5039367187",
      "date": "2024-01-15"
    }
  ]
}

{
  "success": true,
  "results": [
    {
      "phone": "5039367187",
      "legalWindows": [
        {
          "startUTC": "2024-01-15T16:00:00Z",
          "endUTC": "2024-01-16T05:00:00Z"
        }
      ],
      "hasLegalWindow": true
    }
  ]
}

{
  "success": true,
  "results": [
    {
      "phone": "5039367187",
      "legalWindows": [],
      "hasLegalWindow": false
    }
  ]
}

Usage Notes

Times are returned in UTC - convert to local time for display
Some dates may have no legal windows (holidays, emergencies)
Use numberOfDays to get windows for multiple consecutive days
For real-time “can I call now?” checks, use is_time_legal_to_call instead

​When to Use

​Parameters

​Response

​Examples

​Usage Notes

When to Use

Parameters

Response

Examples

Usage Notes