> ## 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.

# get_legal_call_times Tool

> Get legal calling windows for phone numbers on a given date

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

<ParamField body="phoneNumbers" type="array" required>
  Array of objects containing phone numbers and dates.

  <Expandable title="phoneNumber object">
    <ParamField body="phoneNumber" type="string" required>
      10-digit North American phone number (e.g., `"5039367187"`).
    </ParamField>

    <ParamField body="date" type="string" required>
      ISO 8601 date for which to get legal calling times (e.g., `"2024-01-15"`).
    </ParamField>

    <ParamField body="dncProjId" type="string">
      Optional DNCScrub project ID for custom calling hours.
    </ParamField>

    <ParamField body="numberOfDays" type="number">
      Number of days to return (defaults to 1).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="loginId" type="string">
  API key. Only required if not provided via the `x-dncscrub-api-key` HTTP header.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the API call succeeded.
</ResponseField>

<ResponseField name="results" type="array">
  Array of results, one per phone number.

  <Expandable title="result object">
    <ResponseField name="phone" type="string">
      The phone number checked.
    </ResponseField>

    <ResponseField name="legalWindows" type="array">
      Array of legal calling time windows.

      <Expandable title="window object">
        <ResponseField name="startUTC" type="string">
          Start of legal calling window in UTC.
        </ResponseField>

        <ResponseField name="endUTC" type="string">
          End of legal calling window in UTC.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="hasLegalWindow" type="boolean">
      `true` if there is at least one legal window to call.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errorCode" type="string">
  Machine-readable error code (when failed).
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Human-readable error description (when failed).
</ResponseField>

## Examples

<Tabs>
  <Tab title="Request">
    ```json theme={null}
    {
      "phoneNumbers": [
        {
          "phoneNumber": "5039367187",
          "date": "2024-01-15"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "success": true,
      "results": [
        {
          "phone": "5039367187",
          "legalWindows": [
            {
              "startUTC": "2024-01-15T16:00:00Z",
              "endUTC": "2024-01-16T05:00:00Z"
            }
          ],
          "hasLegalWindow": true
        }
      ]
    }
    ```
  </Tab>

  <Tab title="No Window (Holiday)">
    ```json theme={null}
    {
      "success": true,
      "results": [
        {
          "phone": "5039367187",
          "legalWindows": [],
          "hasLegalWindow": false
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## 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