WhenWiz
Log in
Sign up free

API reference

Base URL https://api.whenwiz.com/wp-json/whenwiz/v1.

Send X-Whenwiz-Client on every request. The site sends the login cookie. A device sends Authorization: Bearer. Creating a countdown also sends Idempotency-Key. Updating one sends If-Match with the revision. A published countdown can be read without a credential. The full document is the OpenAPI file.

POST /register

Create an account

No sign-in.

Parameters

  • X-Whenwiz-Client header, required

Body

  • email string, email, required
  • password string, required
  • name string

Response SessionResponse.

POST /session

Sign in

No sign-in.

Parameters

  • X-Whenwiz-Client header, required

Body

  • email string, email, required
  • password string, required

Response SessionResponse.

POST /logout

Sign out

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

GET /account

Read the signed-in account

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response Account.

PATCH /account

Update name and default formats

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • first_name string
  • last_name string
  • date_format month_day_year | day_month_year | weekday_day_month | mdy_numeric | mdy_dots | dmy_numeric | dmy_dots | ymd
  • time_format h12 | h12_lower | h24
  • timezone string — IANA timezone used for new countdowns.

Response Account.

GET /timezones

List canonical IANA timezones

No sign-in.

Parameters

  • X-Whenwiz-Client header, required
  • search query

Response TimezoneList.

GET /places/autocomplete

Search businesses with Google Places

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • q query, required

Response PlaceList.

POST /places/hours

Load the next open or close for a business

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • place_id string, required

Response PlaceHours.

POST /events

Create an event

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • Idempotency-Key header, required

Body

  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind datetime, required
  • config DatetimeConfig, required
    • timezone string — Canonical IANA timezone, or UTC. Abbreviations and numeric offsets are not zones.
    • deadline_at string — Unambiguous ISO 8601 instant ending in Z or a numeric offset. The timezone, when set, is only where that instant is displayed and edited.
    • local_date string — Civil date YYYY-MM-DD.
    • local_time string — Civil time HH:MM.
    • start_now boolean — Start a count-up from the server clock. Stores the civil time in timezone.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind fixed, required
  • config FixedConfig, required
    • timezone string — Canonical IANA timezone, or UTC. Abbreviations and numeric offsets are not zones.
    • deadline_at string — Unambiguous ISO 8601 instant ending in Z or a numeric offset. The timezone, when set, is only where that instant is displayed and edited.
    • local_date string — Civil date YYYY-MM-DD.
    • local_time string — Civil time HH:MM.
    • start_now boolean — Start a count-up from the server clock. Stores the civil time in timezone.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind duration, required
  • config DurationConfig, required
    • duration_seconds integer, required — Length of the timer in seconds, from 1 to 31536000 (one year).
    • state idle | running | paused — Server-owned. A new timer is idle until the actions endpoint starts it.
    • remaining_seconds integer — Server-owned frozen remainder while the timer is paused or idle.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind recurring, required
  • config RecurringConfig, required
    • timezone string — Canonical IANA timezone the civil time repeats in. Omit it to run the schedule in UTC.
    • frequency daily | weekly | monthly | yearly, required — How the countdown rolls forward after each occurrence.
    • local_time string, required — Civil time HH:MM of each occurrence.
    • days_of_week array of integer — Required for weekly. 1 is Monday and 7 is Sunday.
    • day_of_month integer — Required for monthly and yearly. Months or years without that day are skipped.
    • month integer — Required for yearly. 1 is January.
    • annual_date string — A civil date whose month and day repeat each year. The year is not kept.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind personalized, required
  • config PersonalizedConfig, required
    • duration_seconds integer, required — Window length in seconds. Each person's deadline is this long from the moment they are added.
    • external_user_id string, required — Your stable id for the first person. Further people are added with the subjects endpoint.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind business, required
  • config BusinessConfig, required
    • place_id string, required — Google Place id. WhenWiz loads the hours. The browser does not send them.
    • name string — Display name from Google.
    • timezone string — IANA timezone of the place.
    • hours_fetched_at integer — Unix epoch seconds when the hours were last read from Google.
    • closed_dates array of string — Civil dates YYYY-MM-DD that replace the weekly hours and stay shut.
    • dated array of value — Opening intervals that name a civil date, including special days.
    • regular array of value — Weekly opening intervals. Days are 1 (Monday) to 7 (Sunday).
    • boundary open | close | open_ended — What target_at is counting toward.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string

Response Event.

PUT /events/order

Set the countdown order

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • ids array of string, required

PATCH /events/{id}

Update an event

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • If-Match header, required

Body

  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind datetime, required
  • config DatetimeConfig, required
    • timezone string — Canonical IANA timezone, or UTC. Abbreviations and numeric offsets are not zones.
    • deadline_at string — Unambiguous ISO 8601 instant ending in Z or a numeric offset. The timezone, when set, is only where that instant is displayed and edited.
    • local_date string — Civil date YYYY-MM-DD.
    • local_time string — Civil time HH:MM.
    • start_now boolean — Start a count-up from the server clock. Stores the civil time in timezone.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind fixed, required
  • config FixedConfig, required
    • timezone string — Canonical IANA timezone, or UTC. Abbreviations and numeric offsets are not zones.
    • deadline_at string — Unambiguous ISO 8601 instant ending in Z or a numeric offset. The timezone, when set, is only where that instant is displayed and edited.
    • local_date string — Civil date YYYY-MM-DD.
    • local_time string — Civil time HH:MM.
    • start_now boolean — Start a count-up from the server clock. Stores the civil time in timezone.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind duration, required
  • config DurationConfig, required
    • duration_seconds integer, required — Length of the timer in seconds, from 1 to 31536000 (one year).
    • state idle | running | paused — Server-owned. A new timer is idle until the actions endpoint starts it.
    • remaining_seconds integer — Server-owned frozen remainder while the timer is paused or idle.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind recurring, required
  • config RecurringConfig, required
    • timezone string — Canonical IANA timezone the civil time repeats in. Omit it to run the schedule in UTC.
    • frequency daily | weekly | monthly | yearly, required — How the countdown rolls forward after each occurrence.
    • local_time string, required — Civil time HH:MM of each occurrence.
    • days_of_week array of integer — Required for weekly. 1 is Monday and 7 is Sunday.
    • day_of_month integer — Required for monthly and yearly. Months or years without that day are skipped.
    • month integer — Required for yearly. 1 is January.
    • annual_date string — A civil date whose month and day repeat each year. The year is not kept.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind personalized, required
  • config PersonalizedConfig, required
    • duration_seconds integer, required — Window length in seconds. Each person's deadline is this long from the moment they are added.
    • external_user_id string, required — Your stable id for the first person. Further people are added with the subjects endpoint.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string
  • label string, required — Short name shown on the countdown.
  • status draft | private | published — draft and private are visible to the owner. published is readable without a credential. A draft or private id returns the same 404 as a missing id.
  • display until | since | both — until counts down, since counts up, both shows each side.
  • external_ref string — Optional id from another system.
  • poll_interval_seconds integer — Optional per-event poll interval override, in seconds.
  • kind business, required
  • config BusinessConfig, required
    • place_id string, required — Google Place id. WhenWiz loads the hours. The browser does not send them.
    • name string — Display name from Google.
    • timezone string — IANA timezone of the place.
    • hours_fetched_at integer — Unix epoch seconds when the hours were last read from Google.
    • closed_dates array of string — Civil dates YYYY-MM-DD that replace the weekly hours and stay shut.
    • dated array of value — Opening intervals that name a civil date, including special days.
    • regular array of value — Weekly opening intervals. Days are 1 (Monday) to 7 (Sunday).
    • boundary open | close | open_ended — What target_at is counting toward.
  • appearance Appearance — How the countdown is drawn. A preset id expands to that design. Each styled field maps to a CSS variable.
    • preset string — Id of a saved design, or custom.
    • show_card boolean
    • background string
    • border_color string
    • border_width integer
    • border_radius integer
    • show_background boolean
    • background_blur integer
    • background_wash_opacity integer
    • show_status boolean
    • status_font string
    • status_size integer
    • status_color string
    • status_background string
    • status_border_color string
    • status_border_width integer
    • status_radius integer
    • show_icon boolean
    • icon string
    • icon_size integer
    • icon_background string
    • icon_foreground string
    • icon_border_color string
    • icon_border_width integer
    • icon_radius integer
    • show_label boolean
    • label_font string
    • label_size integer
    • label_color string
    • show_datetime boolean
    • show_time boolean
    • show_timezone boolean
    • date_format string
    • time_format account | h12 | h12_lower | h24
    • datetime_font string
    • datetime_size integer
    • datetime_color string
    • show_until boolean
    • until_font string
    • until_size integer
    • until_color string
    • show_countdown boolean
    • hide_zero_units boolean
    • layout units | sleeps | days | split-flap | rings | tear-off
    • day_basis viewer | event
    • countdown_font string
    • countdown_size integer
    • countdown_color string

Response Event.

GET /events/{id}/background

Read the countdown background image

Signed-in account.

Parameters

  • w query — With h, returns a JPEG already fitted, positioned, and blurred for a card of this width.
  • h query — With w, returns a JPEG already fitted, positioned, and blurred for a card of this height.

POST /events/{id}/background

Upload a background image

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response Event.

DELETE /events/{id}/background

Remove the background image

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response Event.

GET /events/{id}/icon

Read the custom icon

Signed-in account.

POST /events/{id}/icon

Upload a custom icon

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response Event.

DELETE /events/{id}/icon

Remove the custom icon

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response Event.

GET /events/{id}/gif

Render an animated GIF of the countdown

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • width query — Image width in pixels. Height follows the countdown.
  • seconds query — Seconds in the loop. Ten seconds is a practical length for email.

POST /events/{id}/actions

Start, pause, resume, or reset a duration timer

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • If-Match header, required

Body

  • action start | pause | resume | reset, required

Response Event.

POST /events/{id}/subjects

Add a person to a personalized timer

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • external_user_id string, required

Response Subject.

POST /pairings

Start device pairing

No sign-in.

Parameters

  • X-Whenwiz-Client header, required

Body

  • client_id string, required
  • device_name string

Response Pairing.

POST /pairings/token

Poll for a device token

No sign-in.

Parameters

  • X-Whenwiz-Client header, required

Body

  • device_code string, required

Response DeviceToken.

POST /pairings/approve

Approve a pairing code

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • user_code string, required — The code shown on the display. The dash is optional.

Response Device.

POST /oauth/authorize

Approve a site connection

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • response_type string, required
  • client_id string, required
  • redirect_uri string, required
  • state string, required
  • code_challenge string, required
  • code_challenge_method string, required

Response OAuthRedirect.

POST /oauth/token

Exchange an authorization code or refresh token

No sign-in.

Parameters

  • X-Whenwiz-Client header, required

Body

  • grant_type string
  • code string
  • redirect_uri string
  • client_id string
  • code_verifier string
  • refresh_token string

Response DeviceToken.

PATCH /device

Update this device

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • name string
  • active_event_id string

Response Device.

GET /device/catalog

List the account countdowns for a paired WordPress site. Drafts are left out.

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response DeviceCatalog.

GET /device/events

List this device's countdowns. Drafts are left out.

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Response EventList.

GET /device/firmware

Check whether a newer firmware image is published

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • X-Whenwiz-Firmware header, required — Firmware version on the device, major.minor.patch.
  • X-Whenwiz-Board header, required — Board id, such as crowpanel-advance-7.

Response FirmwareCheck.

GET /device/firmware/image

Download the published firmware image

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required
  • X-Whenwiz-Board header, required — Board id, such as crowpanel-advance-7.

PUT /devices/{id}/events

Assign events to a device

Signed-in account.

Parameters

  • X-Whenwiz-Client header, required

Body

  • event_ids array of string, required

Response Device.

WhenWiz

About · Docs · Help · Privacy · Terms

© 2026 WhenWiz