Dates and timezones

The API returns timestamps in one of two contracts, chosen per account by the ISO dates option NUACOM switches on: the legacy wall-clock strings most accounts still receive, or ISO 8601 instants with an offset. Which one you get changes how you parse every date field; how you send dates is the same in both. This page covers both contracts, the X-Timezone header, how the date filters you send are read, and the fields that behave differently.

The two contracts#

	Legacy (feature off, the default)	ISO (option on)
Format	2026-05-01 14:30:00. The conversation endpoints and some newer ones already send 2026-05-01T13:30:00.000000Z	2026-05-01T13:30:00+00:00
Timezone	Wall-clock time in your user's profile timezone (on some endpoints the account's), with no offset in the string; the .000000Z values are UTC	UTC by default; the offset of X-Timezone when you send one. Always the same instant
X-Timezone on output	Ignored	Honoured
Fields with no value	A placeholder such as "" or a date truncated to midnight	null

Both example values are the same instant: 13:30 UTC on 1 May 2026, 14:30 in Dublin.

NUACOM enables the feature per account: contact support to have it switched on for yours, test every screen that shows a date, then roll out. Until then, parse both contracts (see Parsing).

Checking which contract you get#

The ISO dates option is switched on per account by NUACOM; ask support whether it is active on yours. GET /v2/user_info carries the user's profile time_zone.

The X-Timezone header#

Send X-Timezone on any /v2/… or /v3/… request to name the timezone the request works in. The timezone query parameter does the same; when both are present the header wins.

• Accepted values: anything PHP's DateTimeZone accepts, that is IANA names (Europe/Dublin, America/New_York), abbreviations (EST) and raw offsets (+05:30). GET /v3/time-zones lists the IANA names. Prefer an IANA name: it follows daylight saving, and it is the only form the emailed exports accept.
• An invalid value never fails the request. Output falls back to UTC; input parsing falls back to your profile timezone, exactly as if you had sent nothing.
• Output, ISO contract only: timestamps are returned with that offset, 2026-05-01T09:30:00-04:00 for America/New_York. Same instant, different label. On the legacy contract the header does not change output; the call log's own timezone parameter still selects the output timezone there.
• Input, both contracts: the date filters you send are read in that timezone, see below.

How the dates you send are read#

Date filters are plain wall-clock strings with no offset, such as 2026-05-01 00:00:00. The API interprets them in, in order: a valid X-Timezone or timezone parameter; otherwise the profile timezone of the user behind the token; otherwise, when the profile has no valid timezone, Europe/Dublin. This is the same on both contracts, so set the header whenever the user picked the dates in a known zone:

# Every call of 1 May 2026, São Paulo time
curl 'https://api.api-nuacom.com/v2/call-log?from_date=2026-05-01%2000:00:00&to_date=2026-05-01%2023:59:59' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Timezone: America/Sao_Paulo'

Inputs read this way: from_date and to_date on GET /v2/call-log, its export and the reports; date on GET /v2/extension-activity. Scheduling inputs follow the same idea: scheduled_for on the conversation endpoints is read in the user's timezone or X-Timezone, send_at and time_to on the SMS endpoints in the user's timezone; see Conversations and Conversations / SMS.

What changes on the ISO contract#

Every timestamp on the endpoints below becomes ISO 8601 in the X-Timezone offset, UTC without the header. By family, with the fields integrators read most:

• Call logs and reports: call_date on GET /v2/call-log, on the call detail GET /v2/call-logs/{callId} together with its notes' note_time, on GET /v2/missed-call-report and the other reports. Legacy: Y-m-d H:i:s in the profile timezone, or in the timezone parameter on the list.
• Conversations and SMS: every timestamp on GET /v2/conversations, GET /v2/conversations/{conversation} and their messages (last_message_at, expires_at, created_at, scheduled_for, submitted_at, delivered_at, read_at and the statuses' timestamps); scheduled_for on POST /v2/sms/history; date on GET /v2/sms, GET /v2/sms/inbox and GET /v2/sms/timeline; time_to on POST /v2/sms/overview; the scheduling fields of GET /v2/conversations/messages/{messageId}. Legacy: the conversation endpoints send ISO in UTC with microseconds (2026-05-01T13:30:00.000000Z) and ignore X-Timezone; the SMS history sends ISO with the profile timezone's offset; the inbox and timeline send Y-m-d H:i:s in the account's timezone.
• Account and users: account_holder.last_login and created_at on GET /v2/account_info (legacy: last_login truncated to midnight, created_at a raw string); last_login on GET /v2/users_list, GET /v3/users and GET /v3/users/me.
• Everything else: created_at, updated_at and deleted_at on contacts (GET /v3/contacts) and the dates of GET /v3/contacts/activity; created_at on GET /v2/payments; start and stop on GET /v2/extension-activity; the dates of GET /v2/call-recording/statistics, GET /v2/client-operations and GET /v2/fax/history, and of the WhatsApp templates, marked mobile numbers and account security settings.

Fields that become null#

On the ISO contract a field with no value is null where the legacy contract made one up. Make these optional before you switch:

• created_at on GET /v2/account_info (legacy: "" when unset); account_holder.last_login is null on both contracts for a holder who never logged in
• last_login on GET /v2/users_list (null on both contracts for a user who never logged in)
• time_to on POST /v2/sms/overview when the message is not scheduled

Fields that never change#

• Calendar dates stay Y-m-d on both contracts and are never shifted: contact_dob in a contact's phonebook, for example. A date of birth has no timezone.
• IVR holiday rules: from_time and to_time on GET /v2/ivr/custom_holiday_settings describe a schedule in the IVR's own timezone. On the ISO contract they carry that timezone's offset, not X-Timezone's: the wall-clock time is the rule.
• Emailed CSV exports (the call-log and missed-call exports) are written as Y-m-d H:i:s in the timezone you named with X-Timezone, if it is an IANA name (an abbreviation or offset is replaced by Europe/Dublin), or in your profile timezone without it. They do not follow the ISO contract.
• V1 endpoints keep their own formats and are not covered here.

Parsing#

• Accept both ISO flavours, 2026-05-01T13:30:00+00:00 and 2026-05-01T13:30:00.000000Z, with any offset. Treat the value as an instant, convert it to the zone you display in, and derive the calendar date after converting, never by slicing the string.
• Keep a fallback for the legacy pattern Y-m-d H:i:s while your account is on the legacy contract or reads an endpoint that keeps it: interpret it in the user's profile timezone (time_zone on GET /v2/user_info), which is what the API wrote it in.
• Treat every timestamp as nullable.
• Do not send X-Timezone for output unless you want the offset to change; convert from UTC on your side and keep one code path. Do send it with date filters, set to the zone the user picked the dates in.