Bring Your Own API for Timezone Inference

Overview

ExpertFlow resolves each contact's timezone and region (jurisdiction) to enforce regional calling-window rules for outbound compliance. By default, the platform uses built-in phone area-code and Canadian postal-code inference.

Bring Your Own API (BYO API) lets you register an HTTPS endpoint — operated by your organization or a trusted geolocation vendor — that ExpertFlow calls when a contact is created or updated. Your API returns the timezone and region used for calling compliance.

This option is intended for organizations that:

• Already maintain accurate location data in a CRM or data warehouse

• Use a specialized geolocation or compliance vendor

• Need higher accuracy than area-code / postal-code inference (e.g. mobile number portability)

When the BYO API is Used

When CHECK_TIMEZONE is enabled and a BYO API is configured for your tenant, resolution follows this priority order:

Integration Model

Request — What ExpertFlow Sends

ExpertFlow sends a JSON object containing the contact fields available at resolution time, plus request metadata for tracing.

Request body example

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "acme-corp",
  "timestamp": "2026-09-01T14:30:00.000Z",
  "customer": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "phoneNumber": ["+14165551212"],
    "postalCode": "M5V 1A1",
    "timezone": null,
    "region": null,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": ["jane.doe@example.com"],
    "addressLine1": "123 King St W",
    "city": "Toronto",
    "state": "ON",
    "country": "CA"
  }
}

Request fields

Metadata (required)

Customer object

The customer object may include additional custom attributes defined in your tenant schema. ExpertFlow does not guarantee every field is populated.

Response — What ExpertFlow Expects

Your API must return JSON with either a successful resolution or an explicit unresolved result.

Successful resolution

{
  "resolved": true,
  "timezone": "America/Toronto",
  "region": "CA-ON",
  "timezoneConfidence": "CONFIRMED",
  "timezoneSource": "EXTERNAL_API"
}

Unresolved (fail closed)

{
  "resolved": false,
  "reason": "INSUFFICIENT_DATA",
  "message": "Phone number and postal code could not be matched to a jurisdiction"
}

Response fields

Success (resolved = true)

Failure (resolved = false)

Standard reason codes

Authentication

Configure how ExpertFlow authenticates to your endpoint:

HTTP Status Codes

Examples

Canadian contact — success

Request: phoneNumber = 4165551212, postalCode = M5V 1A1

Response: timezone = America/Toronto, region = CA-ON, timezoneConfidence = CONFIRMED

US contact — success

Request: phoneNumber = +14155551234, postalCode = 94105, state = CA

Response: timezone = America/Los_Angeles, region = US-CA, timezoneConfidence = CONFIRMED

Unresolved — insufficient data

Request: only firstName and lastName provided

Response: resolved = false, reason = INSUFFICIENT_DATA

ExpertFlow result: contact quarantined (timezoneConfidence = UNRESOLVED_TIMEZONE)

Validation Rules

ExpertFlow validates your response before applying it to the contact:

• timezone must be a valid IANA timezone string

• region must match ^(CA|US)-[A-Z]{2}$ for standard compliance profiles

• Both timezone and region must be present on success

• Invalid or missing fields are treated as unresolved

What ExpertFlow Stores on the Contact

Tenant Configuration (Admin)

Data Privacy

• ExpertFlow sends only contact data required for timezone resolution.

• You are responsible for your vendor's data processing agreements (DPA, GDPR, PIPEDA).

• PII fields (name, phone, email, address) may be included in the request.

• We recommend vendors do not persist full customer payloads unless required for audit.

SLA Recommendations

Limitations (v1)

• No batch/bulk endpoint — one HTTP call per contact

• ExpertFlow does not validate vendor accuracy — you are responsible for data quality