> ## 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`, `RateCenter` | various | Timezone metadata. `RateCenter` is the NPA-NXX's rate center (locality, e.g. `Lloydminster`); `RateCenterLIR` is its Local Interconnection Region, which can name a different city. 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
        RateCenter:
          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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.