Timezone Handling for Workforce API + Workflows

Ensure your workflows display the right times in the right places — whether you're querying availability, assigning work orders, or sending customer notifications.

Summary

All times are stored in UTC. When building workflows or API integrations involving scheduling, availability, or notifications, you must define the timezone used by the service and format times correctly for customers.

Using the x-timezone header

Include the x-timezone header when making API calls to the Workforce module involving scheduling, availability, or work order assignment. This defines the caller's timezone.

Format: Use a valid IANA timezone string, such as America/Toronto, America/Los_Angeles, or America/Phoenix.

x-timezone: America/Toronto

The x-timezone header ensures the service calculates availability correctly. For example, "today" starts and ends at different UTC times depending on the timezone.

When to include it

• Querying technician availability or available time slots
• Assigning or unassigning technicians
• Managing shifts (adding or previewing)
• Searching for available technicians

Passing the x-timezone header improves scheduling accuracy. It also acts as a fallback timezone when formatting notification times if the work order does not have a resolved location timezone.

This header is automatically included when using the Workforce module in the UI. You only need to set it manually in workflows and API integrations.

Using the work order location timezone in notifications

When sending Emails or SMS notifications for work orders, times must display in the timezone where the work takes place.

Step 1: Query the work order timezone

workOrder {
  id
  startDate
  endDate
  location {
    timezone    # e.g., "America/Phoenix"
  }
}

The location.timezone field is automatically set based on the work order coordinates and returns an IANA timezone string.

Step 2: Convert times using location.timezone

Convert UTC timestamps using location.timezone before displaying them in notifications.

Avoid using the scheduler's timezone

Always use the work order location timezone. A dispatcher may schedule work in a different region, but technicians and customers rely on the local appointment time.

Quick reference

Example: Day-before email workflow

Use this pattern to notify technicians of next-day assignments.

1. Trigger: Scheduled trigger (daily)
2. Query: Fetch next-day work orders with location.timezone
3. Format: Convert each startDate using its location.timezone
4. Send: Email the technician with correctly formatted local times

{
  workOrders(filter: { startDate: { gte: $tomorrow, lt: $dayAfter } }) {
    nodes {
      id
      startDate
      location {
        name
        timezone
      }
      primaryTechnician {
        user { email firstName }
      }
    }
  }
}