Forz API v2 — Changelog
The API version is 2026-04-30. Everything below is additive except the
2026-09 removal of the custom_fields:read scope and the 2026-11 replacement of
system_id with system_ids on jobs and recurring jobs; no other field,
endpoint or error code has been renamed or removed since that date, so no client
needs to change its Forz-Version header. A breaking change would
ship as a new dated version and be announced here first.
Each entry names what changed on the wire. Dates are when the change reached production.
2026-11
- Breaking — Jobs: a job can cover several systems at its site, with no
primary.
system_idis removed from jobs and replaced bysystem_ids(array of system UUIDs, in order), readable and writable on create and update. On create, at least one is required when the System module is on, and an omittedsite_idis taken from the first system. On update,system_idsreplaces the whole list through the same rules as the web: systems can be added while the job's status is active, and any system removed only while the job is unscheduled and nothing was recorded for it — a refused change returns422 validation.failedwith the reasons undererrors.systems. A system from another site is rejected the same way. Migrate by sending"system_ids": [<old system_id>]. - Jobs: the
?system_id=list filter now returns jobs covering that system (any of their systems). - Jobs:
?q=also matches the type of any of the job's systems. - Breaking — Recurring jobs:
system_idis replaced by a read-onlysystem_idsarray. - Invoices: a
PATCHthat changes or clearsinvoiceableon an invoice raised on a job, or generated from a billing schedule, is refused with409 invoice.invoiceable_locked, as in the web app. Moving a job's invoice to a project used to succeed and left the job with no invoice; detaching a billing-schedule invoice used to return422 validation.failed. - Jobs: changing a job's
site_idmoves the job's events to the new site's location (map, route planner, mobile), as the web's change-address flow does. They used to keep the old site's coordinates. - Numbers: a supplied
numberlonger than 2000 bytes is refused with422 validation.failed(errors.number) instead of a 500. A supplied number in the active custom format's series with a counter above 2147483647 (e.g.CB2611-9999999999) no longer makes every later auto-numbered create in that module fail; the next number continues after it. - Auth: a key whose user was deleted in Settings > Users (moved to the
Trash Bin) is refused with
403 account.inactive. It used to keep full read and write access. Restoring the user restores the key. - Webhooks:
data.objectnow matchesGET /api/v2/{resource}/{id}.contact.*,item.*andinventory_location.*events, which failed delivery every time, are delivered.assignee_id(jobs, deals, leads, estimates, projects), projectcontract_amountanduser_ids, sitename_addressand line itemitem_nameused to arrivenullor stale. - Webhooks: a delivery answered with a 3xx (or 1xx) is marked
failedand counts toward the circuit breaker, like a 4xx. It used to stayin_flightforever. GET /api/v2/me:api_key.scopeslists only the scopes that still count (the same set asgranted_scopes), not every stored scope.- OpenAPI: contact and contact-linkage
linkable_typeis documented as a free string: contacts linked in the web app report types such asVendor,JoborProject, which the old[Customer, Lead, Site]enum rejected. Writes still accept onlyCustomer,LeadandSite. Toolnumberis documented as an integer, which is what it has always been. Toolheld_sinceis documented asdate-time, notdate: it has always been a full ISO 8601 timestamp. - Scopes: a key's stored scope that the catalog no longer offers
(
available: false, e.g. thewebhooks:*scopes) is ignored: requests that need it return403 auth.scope_missing, andgranted_scopeslists only the scopes that still count. Keys created while those scopes were offered used to keep using them. - Webhooks: endpoint URLs are resolved the way the delivery connection
resolves them, so
localhostand numeric loopback spellings (2130706433,127.1,0x7f000001) are rejected at validation like127.0.0.1, and no verification ping is sent. A host that does not resolve is rejected with422 validation.failed(url"could not be resolved") instead of being saved, and verification reports it asverification.network_unreachable. - Pagination: sorting by a column that can be empty (e.g.
?sort=due_date) now returns every record, with empty values last when ascending and first when descending. It used to skip those records on ascending walks and return500when a page ended on one. - Pagination: a cursor is bound to the endpoint that issued it; replaying
it on another list returns
400 cursor.invalid_filtersinstead of a500. Cursors issued before this change return the same error once; restart from the first page. - Pagination: a non-string
cursor(cursor[a]=b,cursor[]=x) returns400 cursor.invalidinstead of a500. - Filtering: a date or timestamp filter with a year outside 1–9999 returns
400 filter.invalidinstead of a500. - Line items: tax now applies to lines written through the API, as the
schema describes. A new line that omits
tax_rate_idtakes the document's rate when its item istaxable(the web editor's default), and is untaxed otherwise; a line with atax_rate_idgetstax_applied: trueand is taxed at the document's rate;"tax_rate_id": nullmakes an untaxed line. An existing line'stax_appliedchanges only when itstax_rate_iddoes. Lines used to be stored untaxed (tax_applied: false,tax_amount0) whatever was sent. A taxed line on a document with notax_rate_idreturns422 validation.failedontax_rate_id. - ETags: a line item edited in the web app now changes its job,
estimate, invoice or sales order's ETag, and a phone number edited or
removed in the web app changes its contact's ETag (and
updated_at). APATCHcarrying the ETag from before such an edit returns412 precondition.failedinstead of overwriting it. - Line items: a line
tax_rate_idfrom another account (or an unknown id) returns422 validation.failedonlineitems.tax_rate_id; it used to be stored as sent. - Line items: a negative
discount, or adiscount_typeother thanpercent/amount, returns422 validation.failed. A negative amount discount used to raise the line total; an unknown type was stored and discounted nothing. - Out-of-range numbers: a line item
qty,unit_price,discount,positionor labor value too large for its column, or one that makesline_totalreach 100,000,000, returns422 validation.failednaming the field instead of a500. The same holds for project, change order and billing schedule lineamount(10,000,000,000 or more) and billing schedule lineposition. A dealamountof"Infinity"or"NaN"returns422instead of being saved and then failing every read with a500. - Foreign keys:
assignee_id(and Taskuser_id) must be a user in your account, andtax_rate_id(jobs, estimates, invoices, projects),item_category_id,item_subcategory_idand the item account ids, and sitesystem_option_idmust exist in your account. Anything else returns422 validation.failedwith"was not found in this account". These used to be stored as sent (another account's id, an unknown id, or a non-integer user id saved as0), or returned a500. APATCHthat echoes an existing value unchanged is not re-checked. - Tasks:
creator_idis ignored on write, as the schema'sreadOnlysays; aPATCHused to overwrite it. The Taskuser_iddocs no longer call it an assignee alias: it never assigned the task. - Deletes:
DELETEon jobs, estimates, invoices and projects moves the record to the Trash Bin, as the web does, so it can be restored. Jobs were deleted permanently along with their notes, tasks, documents and trashed invoices; estimates, invoices and projects were hidden without a Trash Bin entry. - Malformed bodies: a body that is not valid JSON or not valid UTF-8
returns
400 request.malformedasproblem+json. It used to return an emptytext/html400. The same400 request.malformednow answers a query string with an invalid%-escape or invalid UTF-8 (?x=%ff), which returned atext/plain500, and an unparseableContent-TypeorAcceptheader or an unknown HTTP method, which returned an emptytext/html406 or 405. Its title is now "Malformed request". - Query parameters: a NUL character (
%00) in?q=or any filter returns400 filter.invalidinstead of a500. A non-stringrelated_name(?related_name[a]=b) on/labels,/statusesand/custom_field_definitionsreturns400 filter.invalidinstead of a500; the undocumented array form (?related_name[]=A) is refused too. - Input types: a date sent as a JSON number (
"due_date": 20251301) returns422 validation.failed("is not a valid date") instead of a500. A notedescriptionthat is not a string returns422("must be a string") instead of a500. A string containing a NUL character (\u0000) returns422naming the field ("must not contain a null byte") instead of a500. - Collections:
lineitems,labelsorcustom_fieldsof the wrong type ("lineitems": "abc","labels": "VIP","custom_fields": ["a"]) returns422 validation.failed. The value used to be dropped and the write returned200/201without the change.nullis still ignored. - Out-of-range numbers: any other number too large for its column (e.g.
an item
unit_priceof1e30) returns422 validation.failedonbaseinstead of a500. - Input types: a number, integer or boolean field given a value that is
not one returns
422 validation.failed("is not a number","must be an integer","must be true or false"). Values used to be cast and saved:"abc"as0,"3abc"as3,60.7into an integer field as60, and"maybe"astrue. This covers line itemqty,discountandposition(so"discount": "-5abc"no longer slips past the negative discount check), dealamountandprobability, itemunit_price,unit_cost,reorder_point,taxableandactive, site coordinates andposition, jobdiscount_value, projectallow_overbilling, contact linkageprimary, and integer FKs. Numeric strings ("12.50") and"true"/"false"/"1"/"0"are still accepted. A user id such asassignee_id: "5abc"is refused instead of assigning user 5. - Deals:
probabilitymust be a whole number from 0 to 100 and is documented as an integer.amountis now documented inDealCreateInput(required) andDealUpdateInputas a plain number; a body built from the old schema was always refused. A Money objectamountreturns422. - Change orders:
amountinChangeOrderCreateInputandChangeOrderUpdateInputis documented as a plain number, which is what the endpoint has always read. A Money objectamountreturns422; it used to be dropped, creating the change order at0.00or leaving a PATCH without effect. - Sites:
latitudeoutside −90..90 orlongitudeoutside −180..180 returns422 validation.failed. - Billing schedule lines: a
trigger_statusthat is not a Project statusdisplay_namereturns422 validation.failed. Such a line could never become ready. - Jobs:
discount_total(readOnly) is ignored on writes. It used to be stored as sent.
2026-10
- Line items: a
lineitemsarray with a non-object entry ([null],["x"]) returns422 validation.failed. It used to be read as an empty snapshot and delete every line under a200. - Webhooks:
lead.converted,lead.lostandtask.completednow fire on the default (capitalised) statuses. - Invoices:
GET /api/v2/invoicesaccepts anupdated_atrange filter. - Items:
active: nullreturns422 validation.failed;activeis always a boolean on read. - Idempotency: an empty
Idempotency-Keyheader returns aproblem+json400 idempotency_key.requiredinstead of a plain-text 400. - Spec conformance: every filter the list endpoints accept is now in the OpenAPI document (FK, number and date filters on jobs, estimates, sales orders, sites, tasks, deals, projects, leads, contacts and items).
2026-09
- Custom fields: the
custom_fields:readscope is removed.GET /api/v2/custom_field_definitionsnow returns the groups for every record type the key can read (customers:read→ Customer,systems:read→ SystemOption, …), and no longer needs an admin-owned key. Keys that held the scope keep their other scopes. Bill, Device and DeviceInspection groups are no longer served (no v2 endpoint exposes those records): the list omits them andshowreturns 404. - Custom fields: list endpoints accept custom-field filters; attachment
custom fields can be set and cleared via
PUT/DELETE /api/v2/{resource}/{id}/custom_fields/{field_id}. Stricter input validation on custom field values. - Contacts: contact linkages to customers and sites are exposed; updating a contact no longer replaces an existing primary contact.
- Contacts:
phone_numbersexposed on contact resources. - Spec conformance: the OpenAPI document was audited against the live server and corrected where they disagreed.
- Notes and comments:
GET/POST /api/v2/{resource}/{id}/noteson every parent resource; unmatched/api/v2/*paths now returnproblem+json404s. - Authorization: policy denials report
auth.permission_denied; lookup catalogs are readable by non-admin keys.
2026-07
- Line items:
unit_priceis resolved server-side when omitted on new lines (from the item's price book and the customer's pricing). - Custom fields: fields marked required in the web app are enforced on
POST/PATCHfor jobs. - Estimates: labor visibility and taxability fields on estimate line items.
2026-06
- Jobs:
referenceis persisted; customerreferenceexposed. - Errors:
status.transition_invalidadded to the error code catalog. - List endpoints:
?sort=, field filters (eq,gte,lte,gt,lt,in) and?q=full-text search on every core list endpoint. Each endpoint documents its searchable fields on itsqparameter. - Writes: required fields and allowed values match the web app on every write endpoint.
- Numbering: client-supplied record numbers are respected, checked for collisions and immutable after creation.
- Identity:
GET /api/v2/mereturns the account, user, key scopes and resolvedapi_version. - Systems:
/api/v2/systemsendpoint; relationship integrity checks on foreign keys. - Lookups: statuses lookup;
custom_field_definitionsendpoint (renamed from its preview name).
2026-05
- Errors:
validation.no_topicsadded for webhook endpoints without topics. - Schema:
idand TypeID foreign-key columns documented as UUID strings. - Webhooks: control-plane and lifecycle topics renamed; lifecycle events pre-registered.
- Estimates: customer-facing labor view fields.
- Line items: shared
Lineitemschema across jobs, estimates, invoices and sales orders. - Labels and custom fields: exposed consistently across resources.
2026-04-30 — initial version
- Customers, sites, contacts, jobs, estimates, invoices, sales orders, items, tasks, leads, deals, projects.
- Read-only lookup endpoints.
assignee_idreplacesuser_idon the wire.- Every field annotated with descriptions, enums and
readOnly.