Documentation

Response 200

• status string
• service string
• api_version string
• sms_mode string ("live", "sandbox")

  This process. Whether it would text real people.

• worker_sms_mode string ("live", "sandbox", "unknown")

  The worker that drains StartJob. Conformance requires both sandbox (D249).

• time string, format date-time

Request body

• login_email string, format email required
• password string, format password required

Response 201

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required
• api_key object
  • id integer required
  • name string | null required
  • kind string ("account", "partner", "session") required
  • last_four string | null required
  • last_used_at string | null, format date-time required
  • expires_at string | null, format date-time required — When this key stops working. Null means it does not expire on its own; only `session` keys carry one.
  • created_at string, format date-time required
  • token string required — Shown exactly once. Store it now.

Response 204

No JSON body (or empty success).

Request body

• account object required
  • name string
  • display_name string
  • contact_first_name string
  • contact_email string — Required on standalone signup (D419). Partner-operated create may omit. Where webhook-disable and dead-delivery notices go.
  • contact_phone string — Required on standalone signup (D419). E.164. Where account-level SMS notices go, including the needs_human owner pull-in.
  • owner_sms_alerts boolean — Default true. Set false to handle conversation.needs_human only via webhook. Turning it off without an active needs_human webhook is allowed; owner_alert_cov...
  • website_url string
  • time_zone string
  • vertical string
  • external_ref string
  • brand_color string
  • login_email string, format email — Optional. Set it, with a password, to enable sign-in at `POST /sessions`. Both or neither — a login email with no password is a sign-in that can never succee...
  • password string, format password — Optional, and never returned. Omit both this and `login_email` for an account that is only ever driven by API key, which is the normal case for a partner-pro...
  • serves_minors boolean
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object — Same shape as Account.quiet_hours. Minutes past midnight, evaluated in the RECIPIENT's timezone. The two flat `quiet_hours_*_minute` fields are not accepted.
  • minimum_notice_minutes integer — Minutes before a slot that it may be offered. Defaults to 60. Raise it if the business needs more runway.
  • lapsed_after_days integer — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60.
  • deemed_attendance_after_hours integer | null — Hours an appointment may sit unactioned past its end before it is recorded attended with `attendance_source: deemed`. Null (the default) means never. Only op...
  • review_ask_after_attendances integer — How many attended appointments a family needs before Flywheel asks them for a review, counted across the whole family. Default 1: ask after the first, which ...
  • review_ask_retirement_days integer — Days a family is left alone after a review ask, across every outcome. Default 90, which is what Flywheel has always done. Lengthen-only: shorter than 90 woul...
  • review_url string — Google Place ID or write-a-review URL. A Place ID is stored as `https://search.google.com/local/writereview?placeid=…`. A Maps listing is left as-is. Blank m...
  • google_place_id string — Google Place ID. Opts this account into a live Reviews-page read. We store only the ID. A pasted Place ID in `review_url` is copied here on save.
  • default_location string
  • booking_url string, format uri
  • close_style string ("handoff", "sms_slots", "booking_link")
  • meeting_kind string ("in_person", "at_customer", "virtual")

Response 201

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required
• api_key object
  • id integer required
  • name string | null required
  • kind string ("account", "partner", "session") required
  • last_four string | null required
  • last_used_at string | null, format date-time required
  • expires_at string | null, format date-time required — When this key stops working. Null means it does not expire on its own; only `session` keys carry one.
  • created_at string, format date-time required
  • token string required — Shown exactly once. Store it now.

Response 200

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required

Request body

• account object required
  • name string
  • display_name string
  • contact_first_name string
  • contact_email string — Required on standalone signup (D419). Partner-operated create may omit. Where webhook-disable and dead-delivery notices go.
  • contact_phone string — Required on standalone signup (D419). E.164. Where account-level SMS notices go, including the needs_human owner pull-in.
  • owner_sms_alerts boolean — Default true. Set false to handle conversation.needs_human only via webhook. Turning it off without an active needs_human webhook is allowed; owner_alert_cov...
  • website_url string
  • time_zone string
  • vertical string
  • external_ref string
  • brand_color string
  • login_email string, format email — Optional. Set it, with a password, to enable sign-in at `POST /sessions`. Both or neither — a login email with no password is a sign-in that can never succee...
  • password string, format password — Optional, and never returned. Omit both this and `login_email` for an account that is only ever driven by API key, which is the normal case for a partner-pro...
  • serves_minors boolean
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object — Same shape as Account.quiet_hours. Minutes past midnight, evaluated in the RECIPIENT's timezone. The two flat `quiet_hours_*_minute` fields are not accepted.
  • minimum_notice_minutes integer — Minutes before a slot that it may be offered. Defaults to 60. Raise it if the business needs more runway.
  • lapsed_after_days integer — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60.
  • deemed_attendance_after_hours integer | null — Hours an appointment may sit unactioned past its end before it is recorded attended with `attendance_source: deemed`. Null (the default) means never. Only op...
  • review_ask_after_attendances integer — How many attended appointments a family needs before Flywheel asks them for a review, counted across the whole family. Default 1: ask after the first, which ...
  • review_ask_retirement_days integer — Days a family is left alone after a review ask, across every outcome. Default 90, which is what Flywheel has always done. Lengthen-only: shorter than 90 woul...
  • review_url string — Google Place ID or write-a-review URL. A Place ID is stored as `https://search.google.com/local/writereview?placeid=…`. A Maps listing is left as-is. Blank m...
  • google_place_id string — Google Place ID. Opts this account into a live Reviews-page read. We store only the ID. A pasted Place ID in `review_url` is copied here on save.
  • default_location string
  • booking_url string, format uri
  • close_style string ("handoff", "sms_slots", "booking_link")
  • meeting_kind string ("in_person", "at_customer", "virtual")

Response 200

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required

Response 200

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required

Response 200

• account object

  The tenant, and the voice. Messages in an operated account still speak as the account, never as its operator.

  • id string required — Opaque slug.
  • name string required
  • display_name string | null required
  • contact_first_name string | null required
  • contact_email string | null required — Where mail about the account goes (webhook disable, dead deliveries). Distinct from login_email. Required on standalone signup (D419). Partner-operated creat...
  • contact_phone string | null required — E.164. Where account-level SMS notices go, including the needs_human owner pull-in (D419). Required on standalone signup.
  • website_url string | null required
  • brand_color string | null required
  • time_zone string required — IANA name, e.g. America/Chicago.
  • phone_number string | null required — E.164 sending number.
  • vertical string | null required — Drives which shipped defaults this account falls back to.
  • status string ("active", "paused", "canceled") required
  • serves_minors boolean required — Defaults to true: a business that does not declare gets the protective posture.
  • default_content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • quiet_hours object required — Minutes past midnight, evaluated in the RECIPIENT's timezone. A blocked message is requeued to the next open window, not dropped.
  • minimum_notice_minutes integer | null required — Minutes before a slot that it may be offered. Defaults to 60 so a new lead can still book the same day.
  • deemed_attendance_after_hours integer | null required — When set, an appointment left unactioned this many hours past its end is recorded attended with `attendance_source: deemed`. Null means never.
  • lapsed_after_days integer required — Days after a last visit that a contact with no usual gap between visits yet counts as `lapsed`. Default 60. A contact with two or more visits lapses on their...
  • review_ask_after_attendances integer required — How many attended appointments a family needs before a review is asked for. 1 (the default) asks after the first.
  • review_ask_retirement_days integer required — Days a family is left alone after a review ask. Default 90. The visit-number ceiling scales with this number.
  • review_url string | null required — Where a review ask sends people. Prefer the Google write-a-review URL (`https://search.google.com/local/writereview?placeid=…`). A pasted Place ID is expande...
  • google_place_id string | null required — Google Place ID. Saving one opts the account into a live dashboard read of Google reviews. We store only this field. Review text, ratings, and authors are ne...
  • default_location string | null required — Shop address stamped on in_person bookings and included in the confirmation. Unused when meeting_kind is at_customer or virtual.
  • booking_url string | null required — Public page for picking a time. Used when close_style is booking_link.
  • close_style string ("handoff", "sms_slots", "booking_link") required — How a ready lead books. handoff is the default. Changing this rewrites only the qualify close.
  • meeting_kind string ("in_person", "at_customer", "virtual") required — in_person stamps the account default address. at_customer stamps the contact's address. virtual mints a Whereby room at book time.
  • external_ref string | null required — Your own identifier. Unique across Flywheel when set — two accounts cannot share one.
  • login_email string | null required — Sign-in address for `POST /sessions`. Distinct from `contact_email`, which is only where mail goes and carries no authority. Null on an account driven entire...
  • owner_reachable boolean required — True when contact_email or login_email is present. False means webhook-disable and dead-delivery notices cannot reach the owner; Flywheel operators are the r...
  • owner_sms_alerts boolean required — When true (the default), Flywheel texts the owner on conversation.needs_human for standalone accounts. Partner-operated accounts never get this SMS. Webhook ...
  • owner_alert_coverage string ("operated", "sms", "webhook", "none", "unreachable") required — How an escalate reaches a human. `none` means SMS is off and no active webhook is subscribed to conversation.needs_human — allowed, loud. `unreachable` means...
  • calendar_url string, format uri required — Subscribable ICS feed of this account's appointments, keyed by an unguessable token. Read-only and unauthenticated by design, because calendar apps poll it w...
  • operated_by string | null required — Slug of the operating account, if any.
  • created_at string, format date-time required

Response 200

• phone_number object

  The account's one sending number. `area_code` is present only in the response to the request that provisioned it.

  • number string required — E.164.
  • provider string required
  • area_code string
  • sms boolean required
  • voice boolean required
  • sandbox boolean required — True when this number was invented in sandbox (555-01xx / PNsandbox). A restore of a sandbox dump onto a live host still shows this (D255).

Request body

• area_code string

  Local area code to search first, then adjacent codes. Omit only when retrying an already-provisioned account. Toll-free codes (800, 833, …) are refused.

Response 200

• phone_number object

  The account's one sending number. `area_code` is present only in the response to the request that provisioned it.

  • number string required — E.164.
  • provider string required
  • area_code string
  • sms boolean required
  • voice boolean required
  • sandbox boolean required — True when this number was invented in sandbox (555-01xx / PNsandbox). A restore of a sandbox dump onto a live host still shows this (D255).

Response 200

• message_templates array of object
  • id integer required
  • key string required
  • vertical string | null required
  • channel string ("sms") required — SMS is the only channel. Flywheel is a conversation engine and its only inbound path is SMS, so a channel that cannot carry a reply cannot run a flow.
  • body string required — Supports {{variable}} interpolation.
  • delay_minutes integer | null required — For `nurture.` keys, this is the rung's position in the ladder.
  • guards object required — Halt conditions declared next to the copy they protect: `halt_if_replied`, `halt_if_pipeline_state_in`, `require_pipeline_state_in`.
  • promotional boolean required — Promotional copy requires recorded consent and is never sent without it.
  • transactional boolean required — Transactional copy survives a human takeover and quiet hours. Kept separate from `promotional` on purpose — a qualification question is neither.
  • expects_answer string | null ("boolean", nil) required — `boolean`: the reply to a send of this template is read as yes or no and emitted as `message.answered` (without the reply text). Ignored for keys that are st...
  • active boolean required
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped copy; PATCH/DELETE that id is 422 `not_account_owned`. POST the same key to over...

Request body

• message_template object required
  • key string
  • vertical string
  • channel string ("sms")
  • body string
  • delay_minutes integer
  • active boolean
  • promotional boolean
  • transactional boolean
  • expects_answer string | null ("boolean", nil)
  • guards object

Response 201

• message_template object
  • id integer required
  • key string required
  • vertical string | null required
  • channel string ("sms") required — SMS is the only channel. Flywheel is a conversation engine and its only inbound path is SMS, so a channel that cannot carry a reply cannot run a flow.
  • body string required — Supports {{variable}} interpolation.
  • delay_minutes integer | null required — For `nurture.` keys, this is the rung's position in the ladder.
  • guards object required — Halt conditions declared next to the copy they protect: `halt_if_replied`, `halt_if_pipeline_state_in`, `require_pipeline_state_in`.
  • promotional boolean required — Promotional copy requires recorded consent and is never sent without it.
  • transactional boolean required — Transactional copy survives a human takeover and quiet hours. Kept separate from `promotional` on purpose — a qualification question is neither.
  • expects_answer string | null ("boolean", nil) required — `boolean`: the reply to a send of this template is read as yes or no and emitted as `message.answered` (without the reply text). Ignored for keys that are st...
  • active boolean required
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped copy; PATCH/DELETE that id is 422 `not_account_owned`. POST the same key to over...

Response 200

• carrier_help_overrides array of object
  • account_id string required
  • account_name string required
  • status string ("incomplete", "inactive") required
  • detail string required
  • body string required

Request body

• message_template object required
  • key string
  • vertical string
  • channel string ("sms")
  • body string
  • delay_minutes integer
  • active boolean
  • promotional boolean
  • transactional boolean
  • expects_answer string | null ("boolean", nil)
  • guards object

Response 200

• message_template object
  • id integer required
  • key string required
  • vertical string | null required
  • channel string ("sms") required — SMS is the only channel. Flywheel is a conversation engine and its only inbound path is SMS, so a channel that cannot carry a reply cannot run a flow.
  • body string required — Supports {{variable}} interpolation.
  • delay_minutes integer | null required — For `nurture.` keys, this is the rung's position in the ladder.
  • guards object required — Halt conditions declared next to the copy they protect: `halt_if_replied`, `halt_if_pipeline_state_in`, `require_pipeline_state_in`.
  • promotional boolean required — Promotional copy requires recorded consent and is never sent without it.
  • transactional boolean required — Transactional copy survives a human takeover and quiet hours. Kept separate from `promotional` on purpose — a qualification question is neither.
  • expects_answer string | null ("boolean", nil) required — `boolean`: the reply to a send of this template is read as yes or no and emitted as `message.answered` (without the reply text). Ignored for keys that are st...
  • active boolean required
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped copy; PATCH/DELETE that id is 422 `not_account_owned`. POST the same key to over...

Response 204

No JSON body (or empty success).

Request body

• setup object required
  • data_points array of any — What you need to know about a lead, in plain words, in the order you want it asked.
  • close_style string ("handoff", "sms_slots", "booking_link") — How a ready lead books. Optional; updates the account setting before the draft is built.

Response 201

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required
• warnings array of string

  Rules that could not be applied, in plain words. Empty when every rule compiled.

Response 200

• setup_chat object

  One persistent conversation per account with the setup assistant — the conversational authoring surface for the intake (only the most recent 40 turns are kept).

  • transcript array of object required
  • flow any required — Where the intake stands: the open qualify draft when one exists, else the published version, else null.

Response 204

No JSON body (or empty success).

Request body

• message object required
  • body string — What the owner says, in plain words.

Response 201

• setup_chat object

  One persistent conversation per account with the setup assistant — the conversational authoring surface for the intake (only the most recent 40 turns are kept).

  • transcript array of object required
  • flow any required — Where the intake stands: the open qualify draft when one exists, else the published version, else null.
• reply object
  • say string
  • actions array of string ("set_points", "reword_question", "set_close_style", "publish", "discard_draft") — The actions the server executed this turn. Empty when the assistant only talked or a proposed action was refused.

Parameters

• catalog string ("all")

  `all` returns every shipped default plus the account's own flows, including a shipped qualify the account has already overridden. Omit for the effective catalog: defaults this account would fall back to, minus keys it already owns.

Response 200

• flows array of object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Request body

• flow object required
  • key string
  • vertical string
  • name string
  • active boolean

Response 201

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Request body

• flow object required
  • key string
  • vertical string
  • name string
  • active boolean

Response 200

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Response 204

No JSON body (or empty success).

Response 200

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Response 200

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Response 200

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Response 200

• flow object
  • id integer required
  • key string required
  • vertical string | null required
  • name string | null required
  • active boolean required
  • published boolean required — Live ladders are `true`. Drafts are editable; only published account flows answer real leads via lookup.
  • scope string ("default", "account") required — `account` rows are yours and accept PATCH/DELETE. `default` rows are shipped ladders; PATCH/DELETE that id is 422 `not_account_owned`. `forkFlow` copies one ...
  • setup_source array of object required — The plain-word data points (and rules) `setupIntakeFlow` built this flow from, exactly as submitted — what an editor prefills. `null` for hand-built flows an...
  • steps array of object required

Response 201

• simulation object
  • id integer required — Conversation id — use with advanceFlowSimulation.
  • flow_id integer required
  • contact_id string required
  • outcome string required — FlowRunner outcome for the last turn (e.g. started, advanced, reasked).
  • delivery object | null required — What happened to the last turn's outbound send. halt_reason (e.g. missing_template, guard_failed) explains a turn that produced no message.
  • messages array of object required

Request body

• body string required

  What the lead typed.

Response 200

• simulation object
  • id integer required — Conversation id — use with advanceFlowSimulation.
  • flow_id integer required
  • contact_id string required
  • outcome string required — FlowRunner outcome for the last turn (e.g. started, advanced, reasked).
  • delivery object | null required — What happened to the last turn's outbound send. halt_reason (e.g. missing_template, guard_failed) explains a turn that produced no message.
  • messages array of object required

Response 200

• steps array of object
  • id integer required
  • position integer required
  • template_key string | null required
  • expects string | null ("choice", "number", "boolean", "freeform", "confirm", "name", nil) required
  • writes_to string | null required — Contact field the captured answer lands in, e.g. `age` or `custom_fields.issue`.
  • choices array of object required — ORDERED. Position is what a numbered SMS reply refers to — texting '2' selects the second entry — so this is an array, never an object.
  • branch_on object required — Captured value to next position.
  • route_when object | null required — A judged route: when the captured answer MEANS this plain-word condition ("the dog is a large breed"), the conversation finishes at `position` — an ending st...
  • default_next_position integer | null required — Where to go when no branch matches. Lets branches rejoin somewhere other than the next row.
  • on_confirm_action string | null required
  • terminal boolean required
  • handoff boolean required — A terminal ending whose copy promises a person follows up. Reaching it flags the conversation `flow_handoff` (needs human, owner alerted) and deliberately do...

Request body

• step object required
  • position integer
  • template_key string
  • expects string ("choice", "number", "boolean", "freeform", "confirm", "name")
  • writes_to string
  • choices array of object — ORDERED. Position is what a numbered SMS reply refers to — texting '2' selects the second entry — so this is an array, never an object.
  • branch_on object
  • default_next_position integer
  • on_confirm_action string
  • terminal boolean

Response 201

• step object
  • id integer required
  • position integer required
  • template_key string | null required
  • expects string | null ("choice", "number", "boolean", "freeform", "confirm", "name", nil) required
  • writes_to string | null required — Contact field the captured answer lands in, e.g. `age` or `custom_fields.issue`.
  • choices array of object required — ORDERED. Position is what a numbered SMS reply refers to — texting '2' selects the second entry — so this is an array, never an object.
  • branch_on object required — Captured value to next position.
  • route_when object | null required — A judged route: when the captured answer MEANS this plain-word condition ("the dog is a large breed"), the conversation finishes at `position` — an ending st...
  • default_next_position integer | null required — Where to go when no branch matches. Lets branches rejoin somewhere other than the next row.
  • on_confirm_action string | null required
  • terminal boolean required
  • handoff boolean required — A terminal ending whose copy promises a person follows up. Reaching it flags the conversation `flow_handoff` (needs human, owner alerted) and deliberately do...

Request body

• step object required
  • position integer
  • template_key string
  • expects string ("choice", "number", "boolean", "freeform", "confirm", "name")
  • writes_to string
  • choices array of object — ORDERED. Position is what a numbered SMS reply refers to — texting '2' selects the second entry — so this is an array, never an object.
  • branch_on object
  • default_next_position integer
  • on_confirm_action string
  • terminal boolean

Response 200

• step object
  • id integer required
  • position integer required
  • template_key string | null required
  • expects string | null ("choice", "number", "boolean", "freeform", "confirm", "name", nil) required
  • writes_to string | null required — Contact field the captured answer lands in, e.g. `age` or `custom_fields.issue`.
  • choices array of object required — ORDERED. Position is what a numbered SMS reply refers to — texting '2' selects the second entry — so this is an array, never an object.
  • branch_on object required — Captured value to next position.
  • route_when object | null required — A judged route: when the captured answer MEANS this plain-word condition ("the dog is a large breed"), the conversation finishes at `position` — an ending st...
  • default_next_position integer | null required — Where to go when no branch matches. Lets branches rejoin somewhere other than the next row.
  • on_confirm_action string | null required
  • terminal boolean required
  • handoff boolean required — A terminal ending whose copy promises a person follows up. Reaching it flags the conversation `flow_handoff` (needs human, owner alerted) and deliberately do...

Response 204

No JSON body (or empty success).

Response 200

• faqs array of object
  • id integer required
  • topic string | null required — Set for the suggested question set (`price`, `hours`, `location`, `service_area`, `cancellation`); null for questions the owner wrote themselves.
  • question string required — What a lead would ask. Used to match inbound texts.
  • answer string required — Sent verbatim as the reply, in the owner's own words.
• suggested array of object

  Shipped question prompts this account has not answered yet, in display order.

  • topic string
  • question string
• asked array of object

  Recent lead questions no FAQ answered, newest first, deduped by wording. Each was deferred to a person.

  • question string
  • asked_at string, format date-time

Request body

• faq object required
  • topic string | null ("price", "hours", "location", "service_area", "cancellation", nil) — Answer a suggested question by topic, or omit to write your own.
  • question string — Required when `topic` is omitted.
  • answer string

Response 201

• faq object

  One question leads ask, with the owner's answer. FlowRunner answers a matched question inline — through the shipped `faq.answer` template — instead of treating it as an unclear reply, and the lead keeps their place in the flow.

  • id integer required
  • topic string | null required — Set for the suggested question set (`price`, `hours`, `location`, `service_area`, `cancellation`); null for questions the owner wrote themselves.
  • question string required — What a lead would ask. Used to match inbound texts.
  • answer string required — Sent verbatim as the reply, in the owner's own words.

Request body

• import object

  Give one of the two. `text` wins when both are present.

  • url string — A public page. A bare domain is fetched over https.
  • text string — Any pasted text — a price sheet, an about page, a brochure.

Response 200

• proposals array of object
  • topic string | null
  • question string
  • answer string

Request body

• faq object required
  • topic string | null ("price", "hours", "location", "service_area", "cancellation", nil) — Answer a suggested question by topic, or omit to write your own.
  • question string — Required when `topic` is omitted.
  • answer string

Response 200

• faq object

  One question leads ask, with the owner's answer. FlowRunner answers a matched question inline — through the shipped `faq.answer` template — instead of treating it as an unclear reply, and the lead keeps their place in the flow.

  • id integer required
  • topic string | null required — Set for the suggested question set (`price`, `hours`, `location`, `service_area`, `cancellation`); null for questions the owner wrote themselves.
  • question string required — What a lead would ask. Used to match inbound texts.
  • answer string required — Sent verbatim as the reply, in the owner's own words.

Response 204

No JSON body (or empty success).

Parameters

• pipeline_state string ("new", "engaged", "qualified", "scheduled", "showed", "won", "lost")

  One generic ladder for every vertical. Verticals differ in what the stages mean, not in their shape.

• external_ref string

  Your identifier for this person. Unique per account when set.

• phone string

  Exact E.164. One number is one SMS identity on the account. Use this after a 409 `conflict` on create to find the contact that already holds the number, rather than paging the list.

• open string ("true")

  `true` excludes contacts in `won` or `lost`.

• retention_status string ("lead", "booked", "active", "first_time", "lapsed", "canceled")

  Limits to contacts whose `insights.retention_status` is this value. `lead` includes contacts who have never been booked. — Where a contact's booking history stands, first match wins: `booked` (something live ahead), `canceled` (latest appointment canceled two or more days ago, nothing rebooked), `lapsed` (past twice their usual gap between visits — at least 7 days — or past the account's `lapsed_after_days` with no usual gap yet), `first_time` (one visit three or more days ago, nothing after it), `active` (attended and within their rhythm), `lead` (never attended). Recomputed on every appointment change and nightly.

• created_since string, format date-time

  ISO 8601. Returns contacts created at or after this instant, inclusive. Intended for reconciliation sweeps that compare a recent window rather than paging the whole list. A value that cannot be parsed is refused with `validation_failed` rather than ignored, so a broken filter can never look like an empty result. Pair with `created_before` to walk a window in slices.

• created_before string, format date-time

  ISO 8601. Returns contacts created before this instant, exclusive. Adjacent `[created_since, created_before)` slices therefore partition without overlap, so a sweep that halves a full page can recurse and always terminate (D361). Refused, not ignored, when the value cannot be parsed.

• updated_since string, format date-time

  ISO 8601, inclusive. Returns contacts CHANGED at or after this instant — a different question from `created_since`, which answers who is new. Use this to reconcile: it finds people who arrived long ago and whose consent tier, name or pipeline state moved since you last looked, which is otherwise one request per contact. When this filter is present the list is ordered by `updated_at` ascending (then `id`), so a contact changed during your pagination appears at the end of the walk rather than at a creation page you have already passed (D414). Pair with `updated_before` to walk a window in slices. Without either bound the list is still newest-created first.

• updated_before string, format date-time

  ISO 8601. Returns contacts changed before this instant, exclusive. Adjacent `[updated_since, updated_before)` slices therefore partition without overlap, so a sweep that halves a full page can recurse and always terminate (D415). Same pair as `created_since` / `created_before` (D361). Refused, not ignored, when the value cannot be parsed. Either updated bound orders the list by `updated_at` ascending.

• page integer
• per_page integer

Response 200

• contacts array of object
  • id string required — Opaque slug.
  • name string required — What to call them in a list. Never blank: falls back to the phone, then the email, then `New lead`, so an unnamed lead who has only ever texted is still addr...
  • first_name string | null required
  • last_name string | null required
  • phone string | null required — E.164. Unique per account when set. Inbound SMS is routed by this number; two contacts sharing it would be a routing lottery.
  • email string | null required
  • address string | null required — Where to meet them when the account's meeting_kind is at_customer. Stamped onto a booking at book time.
  • time_zone string | null required
  • age integer | null required
  • age_bucket string | null ("under_13", "13_to_17", "18_plus", nil) required
  • minor boolean required — A minor is never the message recipient; their guardian is.
  • guardian_id string | null required
  • guardian_name string | null required
  • guardian_phone string | null required
  • pipeline_state string ("new", "engaged", "qualified", "scheduled", "showed", "won", "lost") required — One generic ladder for every vertical. Verticals differ in what the stages mean, not in their shape.
  • lost_reason string | null required
  • source string | null required
  • sms_consented boolean required
  • content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_at string | null, format date-time required — When this contact's content tier was last decided, and evidence that it WAS decided. Null means nobody has set it for this person and `content_consent` is si...
  • custom_fields object required — Whatever your flow steps write. This is where domain-specific answers land, which is why Flywheel needs no domain knowledge.
  • external_ref string | null required — Your identifier for this person. Unique per account when set.
  • last_inbound_at string | null, format date-time required
  • created_at string, format date-time required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.

Request body

• contact object required

  Must have a phone, an email, or a guardian phone. Flywheel texts only — email alone records the person and, if you start a conversation, flags the thread `unreachable`.

  • first_name string
  • last_name string
  • phone string — E.164. Unique per account when set.
  • email string
  • address string — Where to meet them. Used when meeting_kind is at_customer; an explicit appointment location still wins.
  • time_zone string — Used for quiet hours. Theirs, not yours.
  • age integer
  • age_bucket string ("under_13", "13_to_17", "18_plus") — When the exact age is unknown. An exact `age` still wins, because the model derives the bucket from it.
  • guardian_name string
  • guardian_phone string
  • source string
  • external_ref string — Your identifier for this person. Unique per account when set. A second create with the same ref returns the existing contact rather than inserting a twin. Bl...
  • content_consent string ("none", "anonymous", "first_name", "photo_video") — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_reason string — Why the tier is being changed. Not stored on the contact — it is kept on the immutable consent event alongside the change, so a trail can answer on what grou...
  • sms_consented boolean — Assert that this person consented to SMS. Recorded as a timestamp and an immutable consent event (never a bare column write). Promotional sending is gated on...
  • custom_fields object
• start_conversation boolean

  Enqueue the first reply on the high-priority lane. Email-only contacts still open a thread, flagged `unreachable` — Flywheel does not send email.

Response 200

• contact object
  • id string required — Opaque slug.
  • name string required — What to call them in a list. Never blank: falls back to the phone, then the email, then `New lead`, so an unnamed lead who has only ever texted is still addr...
  • first_name string | null required
  • last_name string | null required
  • phone string | null required — E.164. Unique per account when set. Inbound SMS is routed by this number; two contacts sharing it would be a routing lottery.
  • email string | null required
  • address string | null required — Where to meet them when the account's meeting_kind is at_customer. Stamped onto a booking at book time.
  • time_zone string | null required
  • age integer | null required
  • age_bucket string | null ("under_13", "13_to_17", "18_plus", nil) required
  • minor boolean required — A minor is never the message recipient; their guardian is.
  • guardian_id string | null required
  • guardian_name string | null required
  • guardian_phone string | null required
  • pipeline_state string ("new", "engaged", "qualified", "scheduled", "showed", "won", "lost") required — One generic ladder for every vertical. Verticals differ in what the stages mean, not in their shape.
  • lost_reason string | null required
  • source string | null required
  • sms_consented boolean required
  • content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_at string | null, format date-time required — When this contact's content tier was last decided, and evidence that it WAS decided. Null means nobody has set it for this person and `content_consent` is si...
  • custom_fields object required — Whatever your flow steps write. This is where domain-specific answers land, which is why Flywheel needs no domain knowledge.
  • external_ref string | null required — Your identifier for this person. Unique per account when set.
  • last_inbound_at string | null, format date-time required
  • created_at string, format date-time required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.

Response 200

• contact object
  • id string required — Opaque slug.
  • name string required — What to call them in a list. Never blank: falls back to the phone, then the email, then `New lead`, so an unnamed lead who has only ever texted is still addr...
  • first_name string | null required
  • last_name string | null required
  • phone string | null required — E.164. Unique per account when set. Inbound SMS is routed by this number; two contacts sharing it would be a routing lottery.
  • email string | null required
  • address string | null required — Where to meet them when the account's meeting_kind is at_customer. Stamped onto a booking at book time.
  • time_zone string | null required
  • age integer | null required
  • age_bucket string | null ("under_13", "13_to_17", "18_plus", nil) required
  • minor boolean required — A minor is never the message recipient; their guardian is.
  • guardian_id string | null required
  • guardian_name string | null required
  • guardian_phone string | null required
  • pipeline_state string ("new", "engaged", "qualified", "scheduled", "showed", "won", "lost") required — One generic ladder for every vertical. Verticals differ in what the stages mean, not in their shape.
  • lost_reason string | null required
  • source string | null required
  • sms_consented boolean required
  • content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_at string | null, format date-time required — When this contact's content tier was last decided, and evidence that it WAS decided. Null means nobody has set it for this person and `content_consent` is si...
  • custom_fields object required — Whatever your flow steps write. This is where domain-specific answers land, which is why Flywheel needs no domain knowledge.
  • external_ref string | null required — Your identifier for this person. Unique per account when set.
  • last_inbound_at string | null, format date-time required
  • created_at string, format date-time required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.

Request body

• contact object required

  Must have a phone, an email, or a guardian phone. Flywheel texts only — email alone records the person and, if you start a conversation, flags the thread `unreachable`.

  • first_name string
  • last_name string
  • phone string — E.164. Unique per account when set.
  • email string
  • address string — Where to meet them. Used when meeting_kind is at_customer; an explicit appointment location still wins.
  • time_zone string — Used for quiet hours. Theirs, not yours.
  • age integer
  • age_bucket string ("under_13", "13_to_17", "18_plus") — When the exact age is unknown. An exact `age` still wins, because the model derives the bucket from it.
  • guardian_name string
  • guardian_phone string
  • source string
  • external_ref string — Your identifier for this person. Unique per account when set. A second create with the same ref returns the existing contact rather than inserting a twin. Bl...
  • content_consent string ("none", "anonymous", "first_name", "photo_video") — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_reason string — Why the tier is being changed. Not stored on the contact — it is kept on the immutable consent event alongside the change, so a trail can answer on what grou...
  • sms_consented boolean — Assert that this person consented to SMS. Recorded as a timestamp and an immutable consent event (never a bare column write). Promotional sending is gated on...
  • custom_fields object

Response 200

• contact object
  • id string required — Opaque slug.
  • name string required — What to call them in a list. Never blank: falls back to the phone, then the email, then `New lead`, so an unnamed lead who has only ever texted is still addr...
  • first_name string | null required
  • last_name string | null required
  • phone string | null required — E.164. Unique per account when set. Inbound SMS is routed by this number; two contacts sharing it would be a routing lottery.
  • email string | null required
  • address string | null required — Where to meet them when the account's meeting_kind is at_customer. Stamped onto a booking at book time.
  • time_zone string | null required
  • age integer | null required
  • age_bucket string | null ("under_13", "13_to_17", "18_plus", nil) required
  • minor boolean required — A minor is never the message recipient; their guardian is.
  • guardian_id string | null required
  • guardian_name string | null required
  • guardian_phone string | null required
  • pipeline_state string ("new", "engaged", "qualified", "scheduled", "showed", "won", "lost") required — One generic ladder for every vertical. Verticals differ in what the stages mean, not in their shape.
  • lost_reason string | null required
  • source string | null required
  • sms_consented boolean required
  • content_consent string ("none", "anonymous", "first_name", "photo_video") required — Ordered most to least restrictive. `anonymous` is the notice-only default; naming or picturing someone requires an actively recorded decision.
  • content_consent_at string | null, format date-time required — When this contact's content tier was last decided, and evidence that it WAS decided. Null means nobody has set it for this person and `content_consent` is si...
  • custom_fields object required — Whatever your flow steps write. This is where domain-specific answers land, which is why Flywheel needs no domain knowledge.
  • external_ref string | null required — Your identifier for this person. Unique per account when set.
  • last_inbound_at string | null, format date-time required
  • created_at string, format date-time required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.

Parameters

• needs_human string ("true")

  `true` returns only threads the bot has escalated.

• page integer
• per_page integer

Response 200

• conversations array of object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`. Here so that rendering a list of threads is one request rather than one per thread.
  • channel_number string | null required
  • flow_key string | null required
  • automation_paused_until string | null, format date-time required — Set 24 hours out whenever a human sends into the thread.
  • automation_paused boolean required — Whether `automation_paused_until` is still in the future. Provided because comparing a timestamp to now is the kind of thing every caller would otherwise get...
  • needs_human boolean required
  • needs_human_at string | null, format date-time required
  • needs_human_reason string | null ("unparsed_reply", "repeated_reschedule", "unreachable", "unanswered_question", "unjudged_rule", "flow_handoff", nil) required — Why the thread was escalated. `unparsed_reply` means the bot could not make sense of the replies; `repeated_reschedule` means this appointment has been moved...
  • message_count integer required
  • last_message_at string | null, format date-time required
  • last_message_direction string | null ("inbound", "outbound", nil) required
  • last_message_preview string | null required — First 140 characters of the most recent message.
  • created_at string, format date-time required

Request body

• conversation object required
  • contact_id string required — Contact id (slug) to open the thread with.

Response 200

• conversation object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`. Here so that rendering a list of threads is one request rather than one per thread.
  • channel_number string | null required
  • flow_key string | null required
  • automation_paused_until string | null, format date-time required — Set 24 hours out whenever a human sends into the thread.
  • automation_paused boolean required — Whether `automation_paused_until` is still in the future. Provided because comparing a timestamp to now is the kind of thing every caller would otherwise get...
  • needs_human boolean required
  • needs_human_at string | null, format date-time required
  • needs_human_reason string | null ("unparsed_reply", "repeated_reschedule", "unreachable", "unanswered_question", "unjudged_rule", "flow_handoff", nil) required — Why the thread was escalated. `unparsed_reply` means the bot could not make sense of the replies; `repeated_reschedule` means this appointment has been moved...
  • message_count integer required
  • last_message_at string | null, format date-time required
  • last_message_direction string | null ("inbound", "outbound", nil) required
  • last_message_preview string | null required — First 140 characters of the most recent message.
  • created_at string, format date-time required

Response 200

• conversation object

  Show payload. Same fields as Conversation, plus `messages`. List and create omit that key (D277).

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`. Here so that rendering a list of threads is one request rather than one per thread.
  • channel_number string | null required
  • flow_key string | null required
  • automation_paused_until string | null, format date-time required — Set 24 hours out whenever a human sends into the thread.
  • automation_paused boolean required — Whether `automation_paused_until` is still in the future. Provided because comparing a timestamp to now is the kind of thing every caller would otherwise get...
  • needs_human boolean required
  • needs_human_at string | null, format date-time required
  • needs_human_reason string | null ("unparsed_reply", "repeated_reschedule", "unreachable", "unanswered_question", "unjudged_rule", "flow_handoff", nil) required — Why the thread was escalated. `unparsed_reply` means the bot could not make sense of the replies; `repeated_reschedule` means this appointment has been moved...
  • message_count integer required
  • last_message_at string | null, format date-time required
  • last_message_direction string | null ("inbound", "outbound", nil) required
  • last_message_preview string | null required — First 140 characters of the most recent message.
  • created_at string, format date-time required
  • messages array of object required

Response 200

• messages array of object
  • id integer required
  • direction string ("inbound", "outbound") required
  • channel string ("sms") required
  • from string | null required
  • to string | null required
  • body string | null required
  • template_key string | null required
  • status string | null required
  • classified_intent string | null required — What the rule-based classifier made of an inbound reply.
  • sent_at string | null, format date-time required
  • created_at string, format date-time required

Request body

• message object required
  • body string required
  • hand_back boolean — Send without pausing automation on this thread.

Response 201

• message object
  • id integer required
  • direction string ("inbound", "outbound") required
  • channel string ("sms") required
  • from string | null required
  • to string | null required
  • body string | null required
  • template_key string | null required
  • status string | null required
  • classified_intent string | null required — What the rule-based classifier made of an inbound reply.
  • sent_at string | null, format date-time required
  • created_at string, format date-time required

Request body

• send object required
  • template_key string required
  • occurrence integer — Distinguishes repeats of the same template to the same person.
  • variables object — Values for the template's {{placeholders}}.

Response 201

• send object

  The outcome of asking us to send a template. `requeued` means held for quiet hours and already scheduled — do not retry it.

  • status string ("sent", "requeued") required
  • message any required
  • scheduled_send_id integer | null required

Response 200

• conversation object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`. Here so that rendering a list of threads is one request rather than one per thread.
  • channel_number string | null required
  • flow_key string | null required
  • automation_paused_until string | null, format date-time required — Set 24 hours out whenever a human sends into the thread.
  • automation_paused boolean required — Whether `automation_paused_until` is still in the future. Provided because comparing a timestamp to now is the kind of thing every caller would otherwise get...
  • needs_human boolean required
  • needs_human_at string | null, format date-time required
  • needs_human_reason string | null ("unparsed_reply", "repeated_reschedule", "unreachable", "unanswered_question", "unjudged_rule", "flow_handoff", nil) required — Why the thread was escalated. `unparsed_reply` means the bot could not make sense of the replies; `repeated_reschedule` means this appointment has been moved...
  • message_count integer required
  • last_message_at string | null, format date-time required
  • last_message_direction string | null ("inbound", "outbound", nil) required
  • last_message_preview string | null required — First 140 characters of the most recent message.
  • created_at string, format date-time required

Response 200

• availability_rules array of object
  • id integer required
  • weekday integer required — 0 is Sunday, matching Ruby's `Date#wday`.
  • start_minute integer required — Minutes from local midnight. Stored as a minute rather than a time because a recurring rule has no date to anchor a time to, and attaching one shifts the win...
  • end_minute integer required — Exclusive, and must be after `start_minute`.
  • appointment_type string required — Which kind of appointment this window is for. Opaque to Flywheel — it only has to match what you ask for slots by.
  • slot_duration_minutes integer required — The window is divided into back-to-back slots of this length. A remainder shorter than one slot is not offered.
  • active boolean required — Inactive rules produce no slots. Appointments already booked inside them are untouched.

Request body

• availability_rule object required
  • weekday integer
  • start_minute integer
  • end_minute integer
  • appointment_type string
  • slot_duration_minutes integer
  • active boolean

Response 201

• availability_rule object

  A recurring weekly window when the account will take appointments.

  • id integer required
  • weekday integer required — 0 is Sunday, matching Ruby's `Date#wday`.
  • start_minute integer required — Minutes from local midnight. Stored as a minute rather than a time because a recurring rule has no date to anchor a time to, and attaching one shifts the win...
  • end_minute integer required — Exclusive, and must be after `start_minute`.
  • appointment_type string required — Which kind of appointment this window is for. Opaque to Flywheel — it only has to match what you ask for slots by.
  • slot_duration_minutes integer required — The window is divided into back-to-back slots of this length. A remainder shorter than one slot is not offered.
  • active boolean required — Inactive rules produce no slots. Appointments already booked inside them are untouched.

Request body

• availability_rule object required
  • weekday integer
  • start_minute integer
  • end_minute integer
  • appointment_type string
  • slot_duration_minutes integer
  • active boolean

Response 200

• availability_rule object

  A recurring weekly window when the account will take appointments.

  • id integer required
  • weekday integer required — 0 is Sunday, matching Ruby's `Date#wday`.
  • start_minute integer required — Minutes from local midnight. Stored as a minute rather than a time because a recurring rule has no date to anchor a time to, and attaching one shifts the win...
  • end_minute integer required — Exclusive, and must be after `start_minute`.
  • appointment_type string required — Which kind of appointment this window is for. Opaque to Flywheel — it only has to match what you ask for slots by.
  • slot_duration_minutes integer required — The window is divided into back-to-back slots of this length. A remainder shorter than one slot is not offered.
  • active boolean required — Inactive rules produce no slots. Appointments already booked inside them are untouched.

Response 204

No JSON body (or empty success).

Parameters

• upcoming string ("true")

  `true` excludes exceptions whose date has passed.

Response 200

• availability_exceptions array of object
  • id integer required
  • date string, format date required — The account's local date.
  • all_day boolean required
  • start_minute integer | null required — Present only for a partial block. Minutes from local midnight.
  • end_minute integer | null required
  • reason string | null required — Free text, for the account's own benefit. Never sent to anyone.

Request body

• availability_exception object required

  Defaults to blocking the whole day. Set `all_day: false` and both minutes to block part of one.

  • date string, format date
  • all_day boolean
  • start_minute integer
  • end_minute integer
  • reason string

Response 201

• availability_exception object

  A day, or part of one, when the recurring rules do not apply.

  • id integer required
  • date string, format date required — The account's local date.
  • all_day boolean required
  • start_minute integer | null required — Present only for a partial block. Minutes from local midnight.
  • end_minute integer | null required
  • reason string | null required — Free text, for the account's own benefit. Never sent to anyone.

Response 204

No JSON body (or empty success).

Parameters

• appointment_type string

  Matches the `appointment_type` on the account's availability rules. Opaque to Flywheel.

• limit integer
• horizon_days integer

  How far ahead to look. Values above 60 are clamped to 60.

Response 200

• slots array of object
  • starts_at string, format date-time required — Pass this back as an appointment's `starts_at` to book it.
  • ends_at string, format date-time required
  • local_date string, format date required — In the account's timezone.
  • local_time string required
  • label string required — Ready to show a human, rendered in the account's timezone.
• time_zone string

  The account's IANA zone — the one every `local_*` field is rendered in.

Parameters

• state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled")

  `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are terminal; `no_show` is reversible to `attended` only.

• upcoming string ("true")

  `true` returns only live appointments still in the future.

• past string ("true")

  `true` returns only appointments whose time has passed, newest first, tiebroken on `id`. Every other listing reads soonest first. The tiebreak matters if you page: two appointments can share a `starts_at`, and without it offset pagination could show one twice and the other never.

• contact_id string

  Limits to one contact, by contact id.

• attended_since string, format date-time

  ISO 8601. Returns appointments whose attendance was RECORDED at or after this instant, inclusive. Note this windows on when attendance was marked, not when the lesson was scheduled — those are different days, and only the former answers "which `appointment.attended` events fired recently", which is what a subscriber reconciling missed webhooks is asking. A lesson from three weeks ago marked attended this morning fired its event this morning. Listing order is still `starts_at` (soonest first, or newest first with `past=true`), not `attended_at` — a newly recorded attendance of a recent lesson can appear on a page already walked. Changing that order waits on `flywheel:appointments:attended_index` printing due (D401 / D457). A value that cannot be parsed is refused with `validation_failed` rather than ignored, so a broken filter can never look like an empty result.

• page integer
• per_page integer

Response 200

• appointments array of object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Request body

• appointment object required
  • contact_id string — Contact SLUG, not an integer — same identifier the contact endpoints use.
  • starts_at string, format date-time — Take this from a slot rather than composing it. An instant not on a slot boundary is accepted, which means you can book outside your own availability if you ...
  • appointment_type string
  • duration_minutes integer — Defaults to the matching availability rule's `slot_duration_minutes`, or 30 if there is no rule.
  • location string
  • meeting_kind string ("in_person", "at_customer", "virtual") — Defaults to the account's meeting_kind.
  • external_ref string — Your identifier for this row. Echoed on the appointment that was created, not on a later reschedule successor.
  • value_cents integer — Optional. What this booking is worth to you, in the currency's minor unit. Send with `value_currency`.
  • value_currency string — ISO 4217, e.g. USD. Stored uppercase.

Response 201

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Request body

• appointment object required
  • value_cents integer | null — Minor units. `null` clears it.
  • value_currency string | null — ISO 4217. `null` clears it.

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Request body

• source string ("confirmed", "deemed", "manual")

  How attendance was decided. `deemed` means nobody said otherwise before the silence window closed, and a subscriber billing on attendance needs to tell that apart from someone actively confirming.

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Request body

• reason string

  Free text, stored verbatim.

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Request body

• appointment object required
  • starts_at string, format date-time required — The new start. Duration, location, contact, and type carry over from the original rather than being re-derived from availability. `external_ref` does not — i...

Response 200

• appointment object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.
• previous object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • contact_phone string | null required — The number this appointment would be reminded on — the contact's, or their guardian's if the contact is a minor.
  • conversation_id integer | null required — The thread it was booked from, when it was booked by text.
  • starts_at string, format date-time required
  • ends_at string, format date-time required
  • local_label string required — The start rendered in the account's timezone.
  • appointment_type string required
  • state string ("booked", "reminded", "attended", "no_show", "canceled", "rescheduled") required — `booked` and `reminded` are the live states — the ones that hold an instant against someone else booking it. `attended`, `canceled` and `rescheduled` are ter...
  • attendance_source any required
  • attended_at string | null, format date-time required
  • no_show_contested_at string | null, format date-time required — When the contact replied that they did attend this no-show. The state stays `no_show`; resolve it with `attend`.
  • canceled_at string | null, format date-time required
  • cancel_reason string | null required
  • location string | null required
  • meeting_kind string ("in_person", "at_customer", "virtual") required
  • join_url string | null required — Flywheel join page for the family. Blank until a virtual room is minted.
  • host_join_url string | null required — Flywheel join page that enters as host. Blank until a virtual room is minted.
  • video_host_joined_at string | null, format date-time required — First time a host entered the Whereby room. Not attendance.
  • video_guest_joined_at string | null, format date-time required — First time a visitor entered the Whereby room. Not attendance.
  • video_session_started_at string | null, format date-time required — Whereby room.session.started — at least two people in the room.
  • video_session_ended_at string | null, format date-time required
  • video_presence_label string | null required — Short room-presence summary for the dashboard. A join is never a charge.
  • notes string | null required
  • value_cents integer | null required — What you said this booking is worth, in the currency's minor unit. Yours, for reporting; Flywheel never sets it or acts on it (D487). Carried to a reschedule...
  • value_currency string | null required — ISO 4217, uppercase. Present exactly when `value_cents` is.
  • external_ref string | null required — Your identifier for this row, echoed back. Not unique, not a list filter, and not an idempotency key (those are interaction captures). A reschedule is a new ...
  • rescheduled_from_id integer | null required — The appointment this row replaced. Null on a first booking. Walk it to reconstruct which times the lesson held, rather than guessing from timestamps (D357).
  • created_at string, format date-time required
  • review_request object | null required — The public-review ask attendance created, when one exists.

Parameters

• state string ("pending", "asked", "reminded", "completed", "declined", "retired", "unreachable")

  There is no transition back to `asked`, which is what caps a request at one ask plus one reminder. `retired` is the 90-day family window closing over an unanswered request. `unreachable` means we could not text them (no number, or STOP); it is listed, not silent, and does not count as having asked.

• open string ("true")

  `true` returns only requests still in `pending`, `asked`, or `reminded`.

• appointment_id integer
• received_since string, format date-time

  ISO 8601. Returns review requests whose review was RECORDED at or after this instant, inclusive. Windows on `received_at`, not request `created_at` — the row is born at attendance and completed days later. When either received bound is present the list is ordered by `received_at` ascending (then `id`) so a newly matching row lands at the end of the walk (D470). Without either bound the list is newest-created first. A value that cannot be parsed is refused with `validation_failed` rather than ignored.

• received_before string, format date-time

  ISO 8601. Returns review requests whose review was recorded before this instant, exclusive. Adjacent `[received_since, received_before)` slices therefore partition (D362). Either received bound orders the list by `received_at` ascending. Refused, not ignored, when the value cannot be parsed.

• page integer
• per_page integer

Response 200

• review_requests array of object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • appointment_id integer | null required — The attended appointment that caused this. At most one request per appointment, enforced by a unique index.
  • state string ("pending", "asked", "reminded", "completed", "declined", "retired", "unreachable") required — There is no transition back to `asked`, which is what caps a request at one ask plus one reminder. `retired` is the 90-day family window closing over an unan...
  • platform string required — Where they are sent to write it.
  • review_url string | null required — Copied from the account at creation. The write-a-review URL the ask will send, never one Flywheel hosts.
  • rating integer | null required — Written when a review is recorded and never read back. Nothing that decides who gets asked can see it, which is what makes gating impossible rather than mere...
  • body string | null required
  • asked_at string | null, format date-time required
  • reminded_at string | null, format date-time required — The one reminder. There is no second.
  • completed_at string | null, format date-time required
  • received_at string | null, format date-time required — When the review was recorded. Same instant as `completed_at` on `complete`. The event clock for `review.received` (D448).
  • created_at string, format date-time required

Response 200

• review_request object

  One review ask. Created by attendance and by nothing else — there is no operation that makes one.

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • appointment_id integer | null required — The attended appointment that caused this. At most one request per appointment, enforced by a unique index.
  • state string ("pending", "asked", "reminded", "completed", "declined", "retired", "unreachable") required — There is no transition back to `asked`, which is what caps a request at one ask plus one reminder. `retired` is the 90-day family window closing over an unan...
  • platform string required — Where they are sent to write it.
  • review_url string | null required — Copied from the account at creation. The write-a-review URL the ask will send, never one Flywheel hosts.
  • rating integer | null required — Written when a review is recorded and never read back. Nothing that decides who gets asked can see it, which is what makes gating impossible rather than mere...
  • body string | null required
  • asked_at string | null, format date-time required
  • reminded_at string | null, format date-time required — The one reminder. There is no second.
  • completed_at string | null, format date-time required
  • received_at string | null, format date-time required — When the review was recorded. Same instant as `completed_at` on `complete`. The event clock for `review.received` (D448).
  • created_at string, format date-time required

Request body

• rating integer
• body string
• source string

  How we learned the review arrived. `google_live` means a dashboard Places name-match; it is never a stored Google review body.

Response 200

• review_request object

  One review ask. Created by attendance and by nothing else — there is no operation that makes one.

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • appointment_id integer | null required — The attended appointment that caused this. At most one request per appointment, enforced by a unique index.
  • state string ("pending", "asked", "reminded", "completed", "declined", "retired", "unreachable") required — There is no transition back to `asked`, which is what caps a request at one ask plus one reminder. `retired` is the 90-day family window closing over an unan...
  • platform string required — Where they are sent to write it.
  • review_url string | null required — Copied from the account at creation. The write-a-review URL the ask will send, never one Flywheel hosts.
  • rating integer | null required — Written when a review is recorded and never read back. Nothing that decides who gets asked can see it, which is what makes gating impossible rather than mere...
  • body string | null required
  • asked_at string | null, format date-time required
  • reminded_at string | null, format date-time required — The one reminder. There is no second.
  • completed_at string | null, format date-time required
  • received_at string | null, format date-time required — When the review was recorded. Same instant as `completed_at` on `complete`. The event clock for `review.received` (D448).
  • created_at string, format date-time required

Response 200

• review_request object

  One review ask. Created by attendance and by nothing else — there is no operation that makes one.

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • appointment_id integer | null required — The attended appointment that caused this. At most one request per appointment, enforced by a unique index.
  • state string ("pending", "asked", "reminded", "completed", "declined", "retired", "unreachable") required — There is no transition back to `asked`, which is what caps a request at one ask plus one reminder. `retired` is the 90-day family window closing over an unan...
  • platform string required — Where they are sent to write it.
  • review_url string | null required — Copied from the account at creation. The write-a-review URL the ask will send, never one Flywheel hosts.
  • rating integer | null required — Written when a review is recorded and never read back. Nothing that decides who gets asked can see it, which is what makes gating impossible rather than mere...
  • body string | null required
  • asked_at string | null, format date-time required
  • reminded_at string | null, format date-time required — The one reminder. There is no second.
  • completed_at string | null, format date-time required
  • received_at string | null, format date-time required — When the review was recorded. Same instant as `completed_at` on `complete`. The event clock for `review.received` (D448).
  • created_at string, format date-time required

Parameters

• contact_id string
• consent_state string ("pending", "granted", "declined")
• granted_since string, format date-time

  ISO 8601. Returns testimonials whose YES was recorded at or after this instant, inclusive. Windows on `granted_at`, not `created_at` or `asked_at`. When either granted bound is present the list is ordered by `granted_at` ascending (then `id`) (D470). Without either bound the list is newest-created first. A value that cannot be parsed is refused with `validation_failed` rather than ignored.

• granted_before string, format date-time

  ISO 8601. Returns testimonials whose YES was recorded before this instant, exclusive. Adjacent `[granted_since, granted_before)` slices therefore partition (D362). Either granted bound orders the list by `granted_at` ascending. Refused, not ignored, when the value cannot be parsed.

• page integer
• per_page integer

Response 200

• testimonials array of object
  • id integer required
  • contact_id string required
  • contact_name string required
  • appointment_id integer | null required
  • quote string required
  • reviewer_name string | null required
  • consent_state string ("pending", "granted", "declined") required
  • asked_at string | null, format date-time required
  • granted_at string | null, format date-time required
  • declined_at string | null, format date-time required
  • created_at string, format date-time required

Request body

• testimonial object required
  • contact_id string — Contact slug.
  • quote string
  • reviewer_name string
  • appointment_id integer

Response 201

• testimonial object

  A first-party quote awaiting or granted site-publish consent.

  • id integer required
  • contact_id string required
  • contact_name string required
  • appointment_id integer | null required
  • quote string required
  • reviewer_name string | null required
  • consent_state string ("pending", "granted", "declined") required
  • asked_at string | null, format date-time required
  • granted_at string | null, format date-time required
  • declined_at string | null, format date-time required
  • created_at string, format date-time required

Parameters

• state string ("open", "queued", "sent", "dismissed", "resolved")

  `open` waits for a decision. `queued` was sent into quiet hours or a pause and goes out when it can. `sent`, `dismissed`, and `resolved` are terminal; `resolved` means the contact booked again or left the segment before anyone followed up.

• segment string ("first_time", "lapsed", "canceled")

  Why a contact was raised. Each has its own template, `reengage.<segment>`.

• contact_id string

  Limits to one contact, by contact id (slug).

• page integer
• per_page integer

Response 200

• follow_ups array of object
  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • segment string ("first_time", "lapsed", "canceled") required — Why a contact was raised. Each has its own template, `reengage.<segment>`.
  • state string ("open", "queued", "sent", "dismissed", "resolved") required — `open` waits for a decision. `queued` was sent into quiet hours or a pause and goes out when it can. `sent`, `dismissed`, and `resolved` are terminal; `resol...
  • template_key string required — The template a send uses.
  • trigger_appointment_id integer required — The appointment the segment was judged from — the last visit, or the canceled one.
  • sent_via string | null ("manual", "auto", nil) required — `manual` when someone pressed send, `auto` when the account's rule sent it.
  • last_error string | null required — Why the last attempt did not send: the Sender's reason (`no_consent`, `opted_out`, `no_phone`, …), `delivery_failed`, or `approved_copy_changed` when auto-se...
  • send_attempts integer required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.
  • queued_at string | null, format date-time required
  • sent_at string | null, format date-time required
  • dismissed_at string | null, format date-time required
  • resolved_at string | null, format date-time required
  • created_at string, format date-time required

Response 200

• follow_up object

  A prompt to get back in touch with one contact. Raised by Flywheel from their history; there is no operation that creates one.

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • segment string ("first_time", "lapsed", "canceled") required — Why a contact was raised. Each has its own template, `reengage.<segment>`.
  • state string ("open", "queued", "sent", "dismissed", "resolved") required — `open` waits for a decision. `queued` was sent into quiet hours or a pause and goes out when it can. `sent`, `dismissed`, and `resolved` are terminal; `resol...
  • template_key string required — The template a send uses.
  • trigger_appointment_id integer required — The appointment the segment was judged from — the last visit, or the canceled one.
  • sent_via string | null ("manual", "auto", nil) required — `manual` when someone pressed send, `auto` when the account's rule sent it.
  • last_error string | null required — Why the last attempt did not send: the Sender's reason (`no_consent`, `opted_out`, `no_phone`, …), `delivery_failed`, or `approved_copy_changed` when auto-se...
  • send_attempts integer required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.
  • queued_at string | null, format date-time required
  • sent_at string | null, format date-time required
  • dismissed_at string | null, format date-time required
  • resolved_at string | null, format date-time required
  • created_at string, format date-time required

Response 200

• follow_up object

  A prompt to get back in touch with one contact. Raised by Flywheel from their history; there is no operation that creates one.

  • id integer required
  • contact_id string required — Contact slug.
  • contact_name string required — Same derivation as `Contact.name`.
  • segment string ("first_time", "lapsed", "canceled") required — Why a contact was raised. Each has its own template, `reengage.<segment>`.
  • state string ("open", "queued", "sent", "dismissed", "resolved") required — `open` waits for a decision. `queued` was sent into quiet hours or a pause and goes out when it can. `sent`, `dismissed`, and `resolved` are terminal; `resol...
  • template_key string required — The template a send uses.
  • trigger_appointment_id integer required — The appointment the segment was judged from — the last visit, or the canceled one.
  • sent_via string | null ("manual", "auto", nil) required — `manual` when someone pressed send, `auto` when the account's rule sent it.
  • last_error string | null required — Why the last attempt did not send: the Sender's reason (`no_consent`, `opted_out`, `no_phone`, …), `delivery_failed`, or `approved_copy_changed` when auto-se...
  • send_attempts integer required
  • insights object required — Their booking history, summarised. Derived from appointments; never written directly. A contact nobody has booked reads as `lead` with an empty history.
  • queued_at string | null, format date-time required
  • sent_at string | null, format date-time required
  • dismissed_at string | null, format date-time required
  • resolved_at string | null, format date-time required
  • created_at string, format date-time required

Response 200

• reengagement_rules array of object
  • segment string ("first_time", "lapsed", "canceled") required — Why a contact was raised. Each has its own template, `reengage.<segment>`.
  • template_key string required
  • auto_send boolean required
  • current_body string | null required — The template as it reads now, placeholders included. Slot times are filled in at send time.
  • approved_body string | null required — The copy that was approved, exactly.
  • approved_at string | null, format date-time required
  • approved_copy_current boolean required — The approved copy still matches the template.
  • auto_send_ready boolean required — `auto_send` is on and the approved copy is current — new follow-ups will send without anyone pressing send.

Request body

• reengagement_rule object required
  • auto_send boolean
  • approve boolean — `true` approves the template as it reads right now.

Response 200

• reengagement_rule object

  Whether one segment's follow-ups send by themselves. Off until both switched on and approved.

  • segment string ("first_time", "lapsed", "canceled") required — Why a contact was raised. Each has its own template, `reengage.<segment>`.
  • template_key string required
  • auto_send boolean required
  • current_body string | null required — The template as it reads now, placeholders included. Slot times are filled in at send time.
  • approved_body string | null required — The copy that was approved, exactly.
  • approved_at string | null, format date-time required
  • approved_copy_current boolean required — The approved copy still matches the template.
  • auto_send_ready boolean required — `auto_send` is on and the approved copy is current — new follow-ups will send without anyone pressing send.

Parameters

• contact_id string

  Contact slug.

• appointment_id integer

  Appointment id.

• page integer
• per_page integer

Response 200

• interaction_captures array of object
  • id integer required
  • contact_id string required — Contact slug.
  • appointment_id integer | null required — Optional appointment this capture is about.
  • body string required — Freeform notes. Flywheel does not interpret them.
  • media_refs array of string required — Opaque refs the subscriber owns (URLs, storage keys). Flywheel does not fetch or host them.
  • external_ref string | null required — Your own idempotency key. Unique per account when set.
  • source string | null required — Opaque label from you (`recap`, `manual`, …). Not interpreted.
  • occurred_at string, format date-time required — When the interaction happened. Defaults to creation time.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Request body

• interaction_capture object required
  • contact_id string — Contact slug. Required on create; ignored on update.
  • appointment_id integer | null — Optional. Must belong to the same account and contact.
  • body string
  • media_refs array of string
  • external_ref string
  • source string
  • occurred_at string, format date-time

Response 201

• interaction_capture object

  What happened with a contact — freeform notes and optional media refs for later content drafts. Vertical-agnostic.

  • id integer required
  • contact_id string required — Contact slug.
  • appointment_id integer | null required — Optional appointment this capture is about.
  • body string required — Freeform notes. Flywheel does not interpret them.
  • media_refs array of string required — Opaque refs the subscriber owns (URLs, storage keys). Flywheel does not fetch or host them.
  • external_ref string | null required — Your own idempotency key. Unique per account when set.
  • source string | null required — Opaque label from you (`recap`, `manual`, …). Not interpreted.
  • occurred_at string, format date-time required — When the interaction happened. Defaults to creation time.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Response 200

• interaction_capture object

  What happened with a contact — freeform notes and optional media refs for later content drafts. Vertical-agnostic.

  • id integer required
  • contact_id string required — Contact slug.
  • appointment_id integer | null required — Optional appointment this capture is about.
  • body string required — Freeform notes. Flywheel does not interpret them.
  • media_refs array of string required — Opaque refs the subscriber owns (URLs, storage keys). Flywheel does not fetch or host them.
  • external_ref string | null required — Your own idempotency key. Unique per account when set.
  • source string | null required — Opaque label from you (`recap`, `manual`, …). Not interpreted.
  • occurred_at string, format date-time required — When the interaction happened. Defaults to creation time.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Request body

• interaction_capture object required
  • contact_id string — Contact slug. Required on create; ignored on update.
  • appointment_id integer | null — Optional. Must belong to the same account and contact.
  • body string
  • media_refs array of string
  • external_ref string
  • source string
  • occurred_at string, format date-time

Response 200

• interaction_capture object

  What happened with a contact — freeform notes and optional media refs for later content drafts. Vertical-agnostic.

  • id integer required
  • contact_id string required — Contact slug.
  • appointment_id integer | null required — Optional appointment this capture is about.
  • body string required — Freeform notes. Flywheel does not interpret them.
  • media_refs array of string required — Opaque refs the subscriber owns (URLs, storage keys). Flywheel does not fetch or host them.
  • external_ref string | null required — Your own idempotency key. Unique per account when set.
  • source string | null required — Opaque label from you (`recap`, `manual`, …). Not interpreted.
  • occurred_at string, format date-time required — When the interaction happened. Defaults to creation time.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Response 204

No JSON body (or empty success).

Parameters

• contact_id string

  Contact slug.

• interaction_capture_id integer

  Interaction capture id.

• testimonial_id integer

  Granted-quote id this draft was assembled from.

• page integer
• per_page integer

Response 200

• draft_suggestions array of object
  • id integer required
  • interaction_capture_id integer | null required — Set when assembled from a job note. Null when the source is a quote.
  • testimonial_id integer | null required — Set when assembled from a granted quote. Null when the source is a capture.
  • contact_id string required — Contact slug.
  • contact_name string required — Display name so a list does not need a second request.
  • title string required
  • body string required
  • status string ("ready", "edited") required — `ready` from the assembler; `edited` after a subscriber PATCH.
  • media_refs array of string required — Copied from the capture (or last edit). Opaque; Flywheel does not host them.
  • allowed boolean required — True only when `violations` is empty at last check.
  • violations array of object required — Snapshot from ConsentGuard. A blocked draft is still stored so you can edit it.
  • source_kind string ("job note", "customer quote") required — What the piece was written from.
  • source_text string | null required — The source material verbatim, so an editor can judge the piece against what it claims to be grounded in. Null if the source row was deleted.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Request body

• draft_suggestion object required
  • interaction_capture_id integer — Create-only. Exactly one of this or `testimonial_id`. Ignored on update.
  • testimonial_id integer — Create-only. Granted quotes only. Exactly one of this or `interaction_capture_id`. Ignored on update.
  • title string — On update: replaces the assembled title and re-checks consent.
  • body string — On update: replaces the assembled body and re-checks consent.
  • media_refs array of string — On update: replaces media refs; presence of any ref is treated as has_media for consent.
  • identifying_terms array of string — Location/school/neighbourhood terms for the re-identification guard. Not stored.

Response 201

• draft_suggestion object

  A content piece written from a capture or granted quote and consent-checked. Not a publish.

  • id integer required
  • interaction_capture_id integer | null required — Set when assembled from a job note. Null when the source is a quote.
  • testimonial_id integer | null required — Set when assembled from a granted quote. Null when the source is a capture.
  • contact_id string required — Contact slug.
  • contact_name string required — Display name so a list does not need a second request.
  • title string required
  • body string required
  • status string ("ready", "edited") required — `ready` from the assembler; `edited` after a subscriber PATCH.
  • media_refs array of string required — Copied from the capture (or last edit). Opaque; Flywheel does not host them.
  • allowed boolean required — True only when `violations` is empty at last check.
  • violations array of object required — Snapshot from ConsentGuard. A blocked draft is still stored so you can edit it.
  • source_kind string ("job note", "customer quote") required — What the piece was written from.
  • source_text string | null required — The source material verbatim, so an editor can judge the piece against what it claims to be grounded in. Null if the source row was deleted.
  • created_at string, format date-time required
  • updated_at string, format date-time required

Response 200

• draft_suggestion object

  A content piece written from a capture or granted quote and consent-checked. Not a publish.

  • id integer required
  • interaction_capture_id integer | null required — Set when assembled from a job note. Null when the source is a quote.
  • testimonial_id integer | null required — Set when assembled from a granted quote. Null when the source is a capture.
  • contact_id string required — Contact slug.
  • contact_name string required — Display name so a list does not need a second request.
  • title string required
  • body string required
  • status string ("ready", "edited") required — `ready` from the assembler; `edited` after a subscriber PATCH.
  • media_refs array of string required — Copied from the capture (or last edit). Opaque; Flywheel does not host them.
  • allowed boolean required — True only when `violations` is empty at last check.
  • violations array of object required — Snapshot from ConsentGuard. A blocked draft is still stored so you can edit it.
  • source_kind string ("job note", "customer quote") required — What the piece was written from.
  • source_text string | null required — The source material verbatim, so an editor can judge the piece against what it claims to be grounded in. Null if the source row was deleted.
  • created_at string, format date-time required
  • updated_at string, format date-time required