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

> Returns timezone information for one or more North American phone numbers

## Response Fields

Every input phone produces exactly one row in the response. Inspect `Status` to decide how to handle each row.

| Field                                                                                                                                  | Type    | Description                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `PhoneNumber`                                                                                                                          | string  | The 10-digit phone number the row applies to                                                                |
| `TZName`, `StateProvince`, `UTCOffset`, `UTCOffsetInMinutes`, `HasDST`, `NextStartDateDST`, `EndStartDateDST`, `LATA`, `RateCenterLIR` | various | Timezone metadata. Populated only when `Status` is `"OK"`; left at default / null values for any non-OK row |
| `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. Timezone fields are valid.                                                                                                                 | Use the result.                         |
| `INVALID_PHONE` | Phone number failed format validation.                                                                                                                                 | Skip; flag the source list for cleanup. |
| `TOLL_FREE`     | Phone is in a toll-free NANP area code (8YY). Non-geographic, so no timezone exists.                                                                                   | Skip; do not retry.                     |
| `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. |

<Note>
  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).
</Note>


## OpenAPI

````yaml POST /v1.5/GeoScrub/GetTimeZoneInfo
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/GetTimeZoneInfo:
    post:
      tags:
        - GeoScrub
      summary: Returns timezone information for one or more North America phone numbers
      parameters:
        - name: loginId
          in: header
          description: LoginId (aka APIKey)
          schema:
            type: string
      requestBody:
        description: "Object of phone numbers whose timezones \r\n            we query"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTimeZoneInfoRequestDTO'
          text/json:
            schema:
              $ref: '#/components/schemas/GetTimeZoneInfoRequestDTO'
          application/*+json:
            schema:
              $ref: '#/components/schemas/GetTimeZoneInfoRequestDTO'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetTimeZoneInfoResponseDTO'
        '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:
    GetTimeZoneInfoRequestDTO:
      type: object
      properties:
        PhoneList:
          type: array
          items:
            type: string
          nullable: true
        OverwriteTodaysTime:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    GetTimeZoneInfoResponseDTO:
      type: object
      properties:
        PhoneNumber:
          type: string
          nullable: true
        TZName:
          type: string
          nullable: true
        StateProvince:
          type: string
          nullable: true
        UTCOffset:
          type: string
          nullable: true
        UTCOffsetInMinutes:
          type: integer
          format: int32
        HasDST:
          type: boolean
        NextStartDateDST:
          type: string
          format: date-time
          nullable: true
        EndStartDateDST:
          type: string
          format: date-time
          nullable: true
        LATA:
          type: string
          nullable: true
        RateCenterLIR:
          type: string
          nullable: true
      additionalProperties: false
    ReasonPhraseError:
      type: object
      properties:
        ReasonPhrase:
          type: string
          description: Description of the error
          nullable: true
      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

````