Skip to main content

API Changelog

What changed in each Rotor API version and how to upgrade.

Written By Noah Sanches

Last updated 3 days ago

API changelog

API versions are dated. Each API key is pinned to one version, and a request can override it with the Rotor-Version header. Each section below lists what changed and how to upgrade from the previous version.

2026-11-14

Breaking changes

  • Auth: Authorization: Bearer <key> replaces x-api-key. Keys pinned to this version are created as dated keys; a legacy key cannot call this version.
  • Version: set by the key's pin, or per request with Rotor-Version: 2026-11-14.
  • Responses: single resources are bare objects, with no status / data wrapper.
  • Lists: { data, total, has_more, next_cursor, previous_cursor }. Cursor paging (cursor, limit 1 to 100) replaces page / limit. total is null unless the request sends include_total=true, which runs a full count.
  • Errors: { error: { code, message, details } }.
  • Visit timing: POST /jobs/{id}/schedule and PATCH /visits/{id} no longer accept end; send duration_minutes.
  • Note attachments: removed. Notes have no attachments, and there are no /note/attachments routes. Lead and customer attachments are unchanged.
  • Messages: provider_message_id and source are removed from the REST message (GET/POST /messages). The message.received webhook payload keeps the shared webhook message shape (provider_message_id, source, errors, attachments { name, url, type, size }), because webhook envelopes are shared across API versions.
  • Quote options: pricing_mode, amount_cents and day_of_month move into cycle, required when billing_mode is cycle and null otherwise.
  • Quote billing_mode: monthly_after_initial_job is removed; it is the old name of cycle, and old options read as cycle.
  • POST /leads: creates, matching an existing lead by phone or email, instead of upserting. See match_on, on_match and matched below.
  • Leads fields:
    • address_* fields become a nested property object.
    • notes string becomes the /leads/{id}/note sub-resource.
    • service_type becomes service_types, an array validated against the company's picklist.
    • assigned_to is an array of user ids and read-only.
    • lead_source is renamed source.
    • value_score is removed.
  • Phone: must parse as a real number, otherwise 400.
  • Timestamps: returned as UTC ISO strings ending in Z; date filters must be ISO 8601.
  • Attachments by URL: the file limit is 25 MB (413 attachment_too_large).
  • Malformed path ids are 400; an id from another company is 404.
  • Timers and timesheets without a start are not listed (they cannot be paged by cursor).
  • POST /webhooks: each event needs the read scope of its data as well as webhooks:write (message.received needs messages:read, job.completed jobs:read, lead.created leads:read, customer.created customers:read), otherwise 403 insufficient_scope.
  • Webhook credentials: a connected app's endpoint stops receiving an event once its connection is revoked, the app is disabled, it loses that event's read scope, or the company's subscription is not active. Endpoints created with an API key belong to the company, like ones made in Settings; revoking, expiring or narrowing the key does not affect them.
  • Malformed bodies: a body that is not valid JSON is 400 invalid_request; one over the size cap is 413 invalid_request, both in the standard error shape.
  • Strict bodies: every write rejects unknown fields with 400, including nested objects.
  • notify_customer defaults to false on POST /jobs, POST /jobs/{id}/schedule, PATCH /visits/{id} and POST /service-plans/{id}/schedule; send true to message the customer.
  • POST /messages: 1,000 API-sent messages per company per UTC day, on top of 30 per minute. Over either limit is 429 rate_limited with Retry-After (until 00:00 UTC for the daily cap).
  • Empty phone or email: "" is 400 on leads and customers; send null to clear.
  • Removed fields: customer has_payment_method, note updated_by, task position, message errors on the REST message (see error).
  • Ids: timesheet, visit timer and property id are numbers, not strings.
  • User references: one shape, { id, name, email }. Crews have owner (replaces owner_user_id) and members[].user; timesheets have user; visit timers have assigned_to as a list of users.
  • Pins: created_by is now assignee (a user or null); pin_type can be null; pins with no location are left out.
  • Timesheets: notes are { content, created_at, user_id }; category is service, sales or office.
  • Messages (REST): error (last delivery error or null) replaces errors; attachments are { url, content_type, size }; status is pending, sent, delivered, received or failed; channel is sms. to must be E.164 and attachment URLs https.
  • Cursors: a malformed or tampered cursor is 400.
  • Jobs: customer, created_at and updated_at can be null.
  • Cycles: amount is null for a rollup, or a variable cycle with no amount.
  • Assessments: a start in the past is 400 on POST /requests and PUT /requests/{id}/assessment.

New

  • PATCH /leads/{id}.
  • Tags sub-resource: POST / PUT /leads/{id}/tags, DELETE /leads/{id}/tags/{tag}.
  • Note sub-resource: GET / PUT /leads/{id}/note (replace), POST /leads/{id}/note/append.
  • Attachments added by URL: POST /leads/{id}/attachments.
  • Idempotency-Key header on POST /leads and the attachment POST.
  • Scope leads:update.
  • Configuration: GET /configuration (includes lead_stages, the company timezone and tax_rates), GET /configuration/line-item-templates (cursor paged, oldest first), GET /configuration/phone-numbers. Needs configuration:read.
  • Users: GET /users (active members, cursor paged, is_technician and role filters), GET /users/{id}, GET /users/{id}/availability (configured weekly hours and exceptions). A user has positions (is_technician, is_salesman, is_office). Needs the new users:read scope.
  • Crews: GET /crews (active crews in display order with current members, cursor paged), GET /crews/{id}/availability (crew weekly hours and exceptions). Needs users:read.
  • SMS messages: GET /messages (cursor paged, newest first), GET /messages/{id}, POST /messages. Scopes messages:read and messages:send. Idempotency-Key on POST /messages.
  • Send limit: 30 POST /messages sends per company per rolling minute, the same rate as the MCP send_message tool; over it, 429 rate_limited with Retry-After. An identical message to the same recipient within 60 seconds is 409 duplicate_message; nothing is sent. Parallel sends can briefly pass the limit.
  • Tasks: GET /tasks, GET /tasks/{id}, POST /tasks (Idempotency-Key), PATCH /tasks/{id}. PATCH rejects an empty body or unknown fields.
  • Visit timers: GET /visit-timers, GET /visit-timers/{id}. Needs visit_timers:read (2026-10-27 checked timesheets:read).
  • Webhook events lead.created and customer.created (payload: data.lead / data.customer, lean; fetch the full record by id). Sent when the record is created in the app, a form, the API, MCP (and Facebook lead ads for leads). Not sent for lead↔customer conversion, the booking widget, CSV import or the mobile map.
  • Timesheets: GET /timesheets, GET /timesheets/{id}.
  • Pins: GET /pins, GET /pin-types (one unpaged list).
  • Quotes: GET /quotes (cursor paged; filters status, lead_id, customer_id, archived), GET /quotes/{id}, POST /quotes (creates a draft with 1 to 4 options; nothing is sent; Idempotency-Key), POST /quotes/{id}/send (sms, email; 202 means queued), POST /quotes/{id}/archive. Scopes quotes:read, quotes:create, quotes:update and quotes:send. Several options need Option Quoting. Errors feature_not_enabled, payments_disabled and quote_locked.
  • Webhooks: POST /webhooks (returns the signing secret once), GET /webhooks, DELETE /webhooks/{id}. Events limited to message.received and job.completed. Scopes webhooks:read and webhooks:write. Errors webhook_limit_reached (10 per company) and webhook_already_exists.
  • Customers: GET /customers (cursor paged; filters status, archived, tags, search, phone, email, created range; expand=note,attachments), GET /customers/{id}, POST /customers (matches by phone or email; on_match merge, error or overwrite; Idempotency-Key), PATCH /customers/{id}. A customer has many properties (is_primary first), billing, lifetime_value (whole dollars, same as the customer page) and payment_methods.
  • Customer sub-resources: POST /customers/{id}/properties, PATCH / DELETE /customers/{id}/properties/{property_id} (is_primary: true makes it primary; delete archives), tags, note and attachments with the same shape as leads.
  • Jobs: GET /jobs (every status by default; filters status, customer_id, service_plan_id, completed range; expand=visits), GET /jobs/{id}, POST /jobs/{id}/schedule (schedules a Pending plan job and creates visit 1; a job with no plan is 404; Idempotency-Key). Jobs carry discounts, amount_received, balance_due, technicians and visit_ids; dates live on visits.
  • Visits: GET /visits (latest start first; filters job_id, customer_id, user_id, crew_id, status, start_date / end_date on start), GET /visits/{id}, PATCH /visits/{id} (reschedule, crew and assignees; notify_assignees defaults to false). Visit ids are integers.
  • Service plans: GET /service-plans, GET /service-plans/{id}. Cycles: GET /cycles, GET /cycles/{id} (amount null for rollup cycles). Both need service_plans:read.
  • Scopes customers:update, jobs:update, visits:read, visits:update. Read-only keys get visits:read; Custom keys must be edited.
  • POST /jobs/{id}/cancel (jobs:update; Idempotency-Key; Completed jobs refused).
  • Errors duplicate_customer, job_not_cancellable, job_not_pending, property_is_primary, property_in_use, visit_not_reschedulable.
  • Requests: GET /requests (newest first; drafts included; filters status, archived, lead_id or customer_id, assigned_to (request or its live assessment), created range), GET /requests/{id}, POST /requests (always published, never a draft; Idempotency-Key), PATCH /requests/{id} (drafts and completed allowed), POST /requests/{id}/archive (the app's delete; cancels a future assessment; already archived returns unchanged; drafts refused), POST /requests/{id}/links (quote, job or service_plan). No delete, restore, complete or reopen. status is derived and read-only.
  • Assessments: one live per request, at PUT /requests/{id}/assessment (book, or move and replace assignees) and DELETE /requests/{id}/assessment (cancel; kept as history). A new or moved assessment sends the "Assessment booked" text when the company has it on. GET /assessments lists a window of at most 92 days (start_date, end_date, user_id), earliest first.
  • Scopes requests:read (also GET /assessments), requests:create, requests:update. Read-only keys get requests:read; Custom keys must be edited. Every requests endpoint needs the company's Requests feature, else 403 feature_not_enabled.
  • Errors request_is_draft (booking, archiving or linking a draft), request_archived (PATCH, assessment PUT / DELETE or links on an archived request) and request_conflict (another change at the same moment; retry).
  • OAuth access tokens for apps registered by Rotor: the same Authorization: Bearer header, limited to the app's scopes. A token works only on dated versions, and shares the company's daily limit.
  • OAuth: reusing an authorization code before it expires is invalid_grant and revokes the connection that code created.
  • GET /me: the company, the credential type (api_key or oauth), the app for an OAuth token, and the granted scopes. Needs no scope.
  • Error company_inactive (403): an OAuth token on a company with no active subscription. API keys are unaffected.
  • Rate limits: 120 requests per minute per company, plus a daily limit (default 10,000, settable per company). Successful responses and 429s carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (daily) and X-RateLimit-Minute-Limit, X-RateLimit-Minute-Remaining and X-RateLimit-Minute-Reset; resets are UTC ISO timestamps. A 429 also carries Retry-After (seconds).
  • Rejected calls (429) do not count toward either limit.
  • Webhooks created with an OAuth token belong to its connection: GET and DELETE /webhooks see only that connection's endpoints, up to 100 per connection. Disconnecting deletes them. API keys see only endpoints created by a key or in Settings.
  • Fix: a lead property location is stored as [lng, lat], the order the app uses; earlier writes swapped it.
  • POST /jobs: creates a one-time job with its first visit. Needs jobs:create. Idempotency-Key.
  • POST /service-plans: creates an inactive plan, with the editor's fields and a quotes-style cycle. Nothing is billed or scheduled. is_auto_pay needs a saved payment method. Needs service_plans:create. Idempotency-Key.
  • POST /service-plans/{id}/schedule: activates a plan with mode pending, first_only or all; the mode must be enabled in the company's service plan settings. Needs service_plans:create. Idempotency-Key.
  • POST /service-plans/{id}/cancel: cancels a plan as the app does (Pending jobs deleted, open jobs cancelled, billing cycles retired). Needs service_plans:update. Idempotency-Key. No webhook fires.
  • Errors schedule_mode_not_enabled, billing_mode_not_enabled, service_plan_already_scheduled, service_plan_cancelled.
  • Customer archive matches the app: archived: true also sets the customer inactive and deactivates its service plans; restoring does not reactivate them. archived: true with status: active is 400.
  • Customer automations: PATCH and match merge or overwrite fire status_change when the status changes.
  • Lead automations, same as the app: creating fires record created, tag added and stage change (starting stage); every update, including tag add, replace and remove, fires record updated, then stage change when the stage changes, then tag added for new tags. Events carry the lead's contact_ref_id.
  • Lead email with several addresses keeps the first and appends the rest to the note, as customers do.
  • POST /messages: a lead_id or customer_id outside the company is 404 not_found; a bare to that belongs to an opted-out contact is 422 message_not_sent.
  • Quotes: POST /quotes/{id}/send honors Idempotency-Key. A quote has total (accepted option once accepted, otherwise recommended; null if none) and client_url (portal link; null when it cannot be built). Create bodies have length caps and deposit_value bounds.
  • notify_customer on PATCH /visits/{id} and POST /jobs/{id}/schedule (default false; send true to message the customer).
  • Scheduling a pending job: if the visit or its assignments cannot be saved, the call fails and the job stays Pending, instead of a Scheduled job with no visit. A job that is no longer Pending at that moment is 409 job_not_pending.
  • Service plans add line_items, discounts, tax_rate_id, notes, service_length_months and property_address. job_counts counts live jobs by real status: scheduled (Scheduled or In Progress), completed, pending; archived, quote and cancelled jobs are not counted. frequency.interval is day, week, month or year.
  • Plan limits on create: service_length_months 1 to 120; frequency.interval_count at most 365 days, 52 weeks, 24 months, 5 years.
  • Cycles add pricing_mode (fixed, rollup, variable) and day_of_month.
  • Jobs add first_visit ({ start, end } or null).
  • Webhook responses list every event an endpoint can hold, including ones set in Settings; POST /webhooks still accepts only the public events.
  • Every operation with an Idempotency-Key documents 409 idempotency_in_progress and 422 idempotency_key_reused.
  • KPIs: GET /kpis (the company's KPIs in app order, one unpaged list), GET /kpis/daily-totals (one row per user, KPI and day, newest day first, cursor paged; filters from, to, kpi_id, user_id). Personal counters are not included. Scope kpis:read. Full access and Read-only keys get it; Custom keys must be edited.

Upgrading from 2026-10-27

2026-10-272026-11-14
Create a key pinned to 2026-10-27Create a new key pinned to 2026-11-14; existing legacy keys cannot move
x-api-key: <key>Authorization: Bearer <key>
{ status, data } wrapperRead the object directly
page, limitcursor (from next_cursor / previous_cursor), limit
{ status: "error", message, ... }{ error: { code, message, details } }
POST /leads upsertsPOST /leads matches on match_on (default phone and email); on_match is merge (default), overwrite or error; read matched
address_street1 … address_countryproperty.address.street1 … property.address.country
notes on the leadGET / PUT /leads/{id}/note, POST /leads/{id}/note/append
service_type (string)service_types (array of picklist values)
lead_sourcesource
assigned_to (string)assigned_to (array of user ids, read-only)
value_scoreRemoved
Invalid phones acceptedInvalid phones return 400
No lead updatePATCH /leads/{id}; key needs leads:update

2026-10-27

Legacy baseline (formerly 1.1.0). Frozen.

Was this helpful?

Still need help? Ask the team