Skip to main content

Changelog

Versioning policy​

  • The contract is connect-v1, served at /api/connect/v1. An incompatible change ships under a new versioned base path.
  • Within connect-v1, changes are additive: new operations, new optional fields, and new values in enums the OpenAPI document doesn't declare closed. Tolerate unknown fields and values, and don't rely on fields the document doesn't list.
  • When a successor version ships, connect-v1 stays available for at least 6 months, and every key owner is emailed before it is retired.

Unreleased​

MCP server

  • MCP server at /api/connect/mcp with OAuth sign-in (no API key). See MCP server.

New operations

  • Customer tags: GET /tags (tags.read), and POST and DELETE /customers/{customer_id}/tags/{tag_id} (customers.write). Customer reads carry tag_ids.
  • PATCH /customers/{customer_id}/consent (customers.write) records an opt-in or opt-out. Customer reads carry consent.
  • POST /leads/{lead_id}/close (leads.write) closes a lead as lost. Lead reads carry closed_reason.
  • POST /service-sets/{service_set_id}/cancel (services.cancel) cancels a recurring service from a date.
  • GET /service-sets/cancel-reasons, GET /jobs/move-reasons and GET /jobs/skip-reasons: the reasons the service cancel, move and skip accept as reason_id. Each needs its action's scope (services.cancel or jobs.change); free.
  • GET /scorecards (scorecards.read): customer ratings of completed visits.

New webhook events: lead.closed, scorecard.submitted, invoice.created, invoice.paid and payment.received, for 18 in all. job.cancelled data.reason adds lock_out and bumped.

New fields and filters

  • updated_since on GET /customers, /homes, /service-sets, /jobs, /leads, /quotes and the per-customer lists.
  • zone_id on homes; customer_sources and each frequency's bookable on GET /quotes/config; pricing.first_visit_minutes on quotes.
  • /usage breakdown[].usage_class can be core_write.

Changed

  • GET /availability has its own rate class (30 a minute, 600 an hour) instead of sharing the report class.
  • A branch can hold 10 active keys, up from 3.
  • Pulse emails key creators at 80% and 100% of the monthly allowance and 14 days before a key expires.
  • customer.created data.source is a named value (manual, quick_book, lead_conversion, connect_api, online_quote, unknown) and is always sent. It previously carried an undocumented number.
  • POST /quotes/{quote_id}/notes moves the lead's status forward, as MaidCentral V2 does: Needs Contacted becomes Contacted, and Quoted becomes Follow-up. It used to leave the status alone. A note also moves the quote's updated_at.
  • A pending job is in_progress or completed from its technicians' time records, and a clock-in or clock-out moves its updated_at.
  • start_date and end_date are published as required on GET /jobs, GET /customers/{customer_id}/jobs, GET /scorecards, GET /time-summaries/daily and GET /time-summaries/jobs. The API already answered 400 invalid_request without them.

OpenAPI document

  • servers lists staging (https://api.staging.maidcentral.ai/api/connect/v1, external pilot partners) first, then production (https://api.maidcentral.ai/api/connect/v1).

  • Schema names are short and stable, for example ConnectJobResponse instead of MaidCentralMultiTenantWebEndpointsConnectJobsConnectJobResponse. Requests and responses are unchanged. Code that refers to generated type names, or reads components.schemas by name, must regenerate.

  • Every response field has a description.

  • Each webhook payload is a named schema under components.schemas (for example ConnectCustomerCreatedEvent, ConnectTestEvent), referenced from x-webhooks, so a generated client gets one type per event.

1.0.0-pilot​

The first contract, for pilot branches. Reads for customers, homes, service sets, jobs, operations, billing, sales, time tracking and seven reports; customer, home, lead and quote writes, quote booking, job move, skip and cancel, and notes; save-card payment links; and webhooks with 13 event types.