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>replacesx-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/datawrapper. - Lists:
{ data, total, has_more, next_cursor, previous_cursor }. Cursor paging (cursor,limit1 to 100) replacespage/limit.totalisnullunless the request sendsinclude_total=true, which runs a full count. - Errors:
{ error: { code, message, details } }. - Visit timing:
POST /jobs/{id}/scheduleandPATCH /visits/{id}no longer acceptend; sendduration_minutes. - Note attachments: removed. Notes have no
attachments, and there are no/note/attachmentsroutes. Lead and customer attachments are unchanged. - Messages:
provider_message_idandsourceare removed from the REST message (GET/POST /messages). Themessage.receivedwebhook 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_centsandday_of_monthmove intocycle, required whenbilling_modeiscycleand null otherwise. - Quote
billing_mode:monthly_after_initial_jobis removed; it is the old name ofcycle, and old options read ascycle. POST /leads: creates, matching an existing lead by phone or email, instead of upserting. Seematch_on,on_matchandmatchedbelow.- Leads fields:
address_*fields become a nestedpropertyobject.notesstring becomes the/leads/{id}/notesub-resource.service_typebecomesservice_types, an array validated against the company's picklist.assigned_tois an array of user ids and read-only.lead_sourceis renamedsource.value_scoreis 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
startare not listed (they cannot be paged by cursor). POST /webhooks: each event needs the read scope of its data as well aswebhooks:write(message.receivedneedsmessages:read,job.completedjobs:read,lead.createdleads:read,customer.createdcustomers:read), otherwise 403insufficient_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 413invalid_request, both in the standard error shape. - Strict bodies: every write rejects unknown fields with 400, including nested objects.
notify_customerdefaults tofalseonPOST /jobs,POST /jobs/{id}/schedule,PATCH /visits/{id}andPOST /service-plans/{id}/schedule; sendtrueto 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 429rate_limitedwithRetry-After(until 00:00 UTC for the daily cap).- Empty phone or email:
""is 400 on leads and customers; sendnullto clear. - Removed fields: customer
has_payment_method, noteupdated_by, taskposition, messageerrorson the REST message (seeerror). - Ids: timesheet, visit timer and property
idare numbers, not strings. - User references: one shape,
{ id, name, email }. Crews haveowner(replacesowner_user_id) andmembers[].user; timesheets haveuser; visit timers haveassigned_toas a list of users. - Pins:
created_byis nowassignee(a user or null);pin_typecan be null; pins with no location are left out. - Timesheets:
notesare{ content, created_at, user_id };categoryisservice,salesoroffice. - Messages (REST):
error(last delivery error or null) replaceserrors;attachmentsare{ url, content_type, size };statusispending,sent,delivered,receivedorfailed;channelissms.tomust be E.164 and attachment URLs https. - Cursors: a malformed or tampered
cursoris 400. - Jobs:
customer,created_atandupdated_atcan be null. - Cycles:
amountis null for a rollup, or a variable cycle with no amount. - Assessments: a
startin the past is 400 onPOST /requestsandPUT /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-Keyheader onPOST /leadsand the attachmentPOST.- Scope
leads:update. - Configuration:
GET /configuration(includeslead_stages, the companytimezoneandtax_rates),GET /configuration/line-item-templates(cursor paged, oldest first),GET /configuration/phone-numbers. Needsconfiguration:read. - Users:
GET /users(active members, cursor paged,is_technicianandrolefilters),GET /users/{id},GET /users/{id}/availability(configured weekly hours and exceptions). A user haspositions(is_technician,is_salesman,is_office). Needs the newusers:readscope. - Crews:
GET /crews(active crews in display order with current members, cursor paged),GET /crews/{id}/availability(crew weekly hours and exceptions). Needsusers:read. - SMS messages:
GET /messages(cursor paged, newest first),GET /messages/{id},POST /messages. Scopesmessages:readandmessages:send.Idempotency-KeyonPOST /messages. - Send limit: 30
POST /messagessends per company per rolling minute, the same rate as the MCPsend_messagetool; over it, 429rate_limitedwithRetry-After. An identical message to the same recipient within 60 seconds is 409duplicate_message; nothing is sent. Parallel sends can briefly pass the limit. - Tasks:
GET /tasks,GET /tasks/{id},POST /tasks(Idempotency-Key),PATCH /tasks/{id}.PATCHrejects an empty body or unknown fields. - Visit timers:
GET /visit-timers,GET /visit-timers/{id}. Needsvisit_timers:read(2026-10-27 checkedtimesheets:read). - Webhook events
lead.createdandcustomer.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; filtersstatus,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. Scopesquotes:read,quotes:create,quotes:updateandquotes:send. Several options need Option Quoting. Errorsfeature_not_enabled,payments_disabledandquote_locked. - Webhooks:
POST /webhooks(returns the signingsecretonce),GET /webhooks,DELETE /webhooks/{id}. Events limited tomessage.receivedandjob.completed. Scopeswebhooks:readandwebhooks:write. Errorswebhook_limit_reached(10 per company) andwebhook_already_exists. - Customers:
GET /customers(cursor paged; filtersstatus,archived,tags,search,phone,email, created range;expand=note,attachments),GET /customers/{id},POST /customers(matches by phone or email;on_matchmerge,errororoverwrite;Idempotency-Key),PATCH /customers/{id}. A customer has manyproperties(is_primaryfirst),billing,lifetime_value(whole dollars, same as the customer page) andpayment_methods. - Customer sub-resources:
POST /customers/{id}/properties,PATCH/DELETE /customers/{id}/properties/{property_id}(is_primary: truemakes it primary; delete archives), tags, note and attachments with the same shape as leads. - Jobs:
GET /jobs(every status by default; filtersstatus,customer_id,service_plan_id, completed range;expand=visits),GET /jobs/{id},POST /jobs/{id}/schedule(schedules aPendingplan job and creates visit 1; a job with no plan is 404;Idempotency-Key). Jobs carrydiscounts,amount_received,balance_due,techniciansandvisit_ids; dates live on visits. - Visits:
GET /visits(latest start first; filtersjob_id,customer_id,user_id,crew_id,status,start_date/end_dateon start),GET /visits/{id},PATCH /visits/{id}(reschedule, crew and assignees;notify_assigneesdefaults to false). Visit ids are integers. - Service plans:
GET /service-plans,GET /service-plans/{id}. Cycles:GET /cycles,GET /cycles/{id}(amountnull for rollup cycles). Both needservice_plans:read. - Scopes
customers:update,jobs:update,visits:read,visits:update. Read-only keys getvisits: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; filtersstatus,archived,lead_idorcustomer_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,joborservice_plan). No delete, restore, complete or reopen.statusis derived and read-only. - Assessments: one live per request, at
PUT /requests/{id}/assessment(book, or move and replace assignees) andDELETE /requests/{id}/assessment(cancel; kept as history). A new or moved assessment sends the "Assessment booked" text when the company has it on.GET /assessmentslists a window of at most 92 days (start_date,end_date,user_id), earliest first. - Scopes
requests:read(alsoGET /assessments),requests:create,requests:update. Read-only keys getrequests:read; Custom keys must be edited. Every requests endpoint needs the company's Requests feature, else 403feature_not_enabled. - Errors
request_is_draft(booking, archiving or linking a draft),request_archived(PATCH, assessmentPUT/DELETEor links on an archived request) andrequest_conflict(another change at the same moment; retry). - OAuth access tokens for apps registered by Rotor: the same
Authorization: Bearerheader, 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_grantand revokes the connection that code created. GET /me: the company, the credential type (api_keyoroauth), 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-RemainingandX-RateLimit-Reset(daily) andX-RateLimit-Minute-Limit,X-RateLimit-Minute-RemainingandX-RateLimit-Minute-Reset; resets are UTC ISO timestamps. A 429 also carriesRetry-After(seconds). - Rejected calls (429) do not count toward either limit.
- Webhooks created with an OAuth token belong to its connection:
GETandDELETE /webhookssee 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
locationis stored as[lng, lat], the order the app uses; earlier writes swapped it. POST /jobs: creates a one-time job with its first visit. Needsjobs:create.Idempotency-Key.POST /service-plans: creates an inactive plan, with the editor's fields and a quotes-stylecycle. Nothing is billed or scheduled.is_auto_payneeds a saved payment method. Needsservice_plans:create.Idempotency-Key.POST /service-plans/{id}/schedule: activates a plan with modepending,first_onlyorall; the mode must be enabled in the company's service plan settings. Needsservice_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). Needsservice_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: truealso sets the customer inactive and deactivates its service plans; restoring does not reactivate them.archived: truewithstatus: activeis 400. - Customer automations:
PATCHand match merge or overwrite firestatus_changewhen 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: alead_idorcustomer_idoutside the company is 404not_found; a baretothat belongs to an opted-out contact is 422message_not_sent.- Quotes:
POST /quotes/{id}/sendhonorsIdempotency-Key. A quote hastotal(accepted option once accepted, otherwise recommended; null if none) andclient_url(portal link; null when it cannot be built). Create bodies have length caps anddeposit_valuebounds. notify_customeronPATCH /visits/{id}andPOST /jobs/{id}/schedule(defaultfalse; sendtrueto 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_monthsandproperty_address.job_countscounts live jobs by real status:scheduled(Scheduled or In Progress),completed,pending; archived, quote and cancelled jobs are not counted.frequency.intervalisday,week,monthoryear. - Plan limits on create:
service_length_months1 to 120;frequency.interval_countat most 365 days, 52 weeks, 24 months, 5 years. - Cycles add
pricing_mode(fixed,rollup,variable) andday_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 /webhooksstill accepts only the public events. - Every operation with an
Idempotency-Keydocuments 409idempotency_in_progressand 422idempotency_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; filtersfrom,to,kpi_id,user_id). Personal counters are not included. Scopekpis:read. Full access and Read-only keys get it; Custom keys must be edited.
Upgrading from 2026-10-27
2026-10-27
Legacy baseline (formerly 1.1.0). Frozen.
Was this helpful?
Still need help? Ask the team