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

> Real-time check if it's legal to call based on time restrictions

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

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

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

    <ParamField body="callProposedDateTimeInUTC" type="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.**
    </ParamField>

    <ParamField body="dncProjId" type="string">
      Optional DNCScrub project ID for custom calling hours.
    </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="isCallPermitted" type="boolean">
      `true` if calling is legal at the proposed time.
    </ResponseField>

    <ResponseField name="secondsRemaining" type="number">
      Seconds remaining in legal calling window (0 if not permitted).
    </ResponseField>

    <ResponseField name="minutesRemaining" type="number">
      Minutes remaining in legal calling window for convenience.
    </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",
          "callProposedDateTimeInUTC": "2024-01-15T18:30:00Z"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Permitted">
    ```json theme={null}
    {
      "success": true,
      "results": [
        {
          "phone": "5039367187",
          "isCallPermitted": true,
          "secondsRemaining": 7200,
          "minutesRemaining": 120
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Not Permitted">
    ```json theme={null}
    {
      "success": true,
      "results": [
        {
          "phone": "5039367187",
          "isCallPermitted": false,
          "secondsRemaining": 0,
          "minutesRemaining": 0
        }
      ]
    }
    ```
  </Tab>
</Tabs>

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