{ "openapi": "3.0.3", "info": { "title": "Breezy Public Reporting API", "version": "1.0.0", "description": "Read customers, team members, jobs, visits, assignments, installed equipment, captured form responses, time entries, configured-period timesheets, business reference catalogs, job leads, estimates, invoices, payments, refunds, recorded job financials, saved sold/earned credits, and financial summaries for your company. Existing API keys grant company-wide read access. Amounts are integer USD cents. Reads return current corrected records, with cursor pagination for collecting results.\n\nRead the [Breezy FSM guides](https://developers.getbreezyapp.com) for authentication, pagination, refresh limits, and business measures. All reads use latest corrected company records; cursors do not create a snapshot or a complete change feed." }, "servers": [ { "url": "https://api.getbreezyapp.com/v1", "description": "Breezy FSM production API" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Company" }, { "name": "Invoices" }, { "name": "Payments" }, { "name": "Refunds" }, { "name": "Reports" }, { "name": "TeamMembers" }, { "name": "Accounts" }, { "name": "Contacts" }, { "name": "Locations" }, { "name": "Jobs" }, { "name": "JobAppointments" }, { "name": "JobAssignments" }, { "name": "BusinessUnits" }, { "name": "JobTypes" }, { "name": "JobClasses" }, { "name": "JobLifecycles" }, { "name": "LeadSources" }, { "name": "Tags" }, { "name": "Estimates" }, { "name": "JobLeads" }, { "name": "Equipment" }, { "name": "FormResponses" }, { "name": "TimeEntries" }, { "name": "Timesheets" }, { "name": "JobFinancials" }, { "name": "RevenueAttributions" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Existing Breezy API key. Grants all published reads in its associated company. No app permission scopes." } }, "schemas": { "Reference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "NullableReference": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "InvoiceStatus": { "type": "string", "enum": [ "DRAFT", "OPEN", "PAID", "VOIDED", "UNCOLLECTABLE" ] }, "PaymentStatus": { "type": "string", "enum": [ "SUBMITTING", "PENDING", "PAID", "FAILED", "CANCELED", "PROCESSING" ] }, "NullablePaymentStatus": { "type": "string", "nullable": true, "enum": [ "SUBMITTING", "PENDING", "PAID", "FAILED", "CANCELED", "PROCESSING", null ] }, "RefundStatus": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "CANCELED" ] }, "PaymentMethod": { "type": "string", "enum": [ "CARD", "ACH", "CASH", "CHECK", "PAYPAL", "VENMO", "CASHAPP", "OTHER", "WISETACK_LOAN" ] }, "JobClass": { "type": "string", "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN" ] }, "NullableJobClass": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "ResponseMeta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } }, "required": [ "request_id", "generated_at", "timezone" ], "description": "Generation time and company timezone. generated_at is not a snapshot or synchronization token." }, "Pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque continuation. Null ends traversal. Keep the same filters; page size may change." } }, "required": [ "next_cursor" ] }, "Company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "timezone": { "type": "string", "description": "IANA company timezone." }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "id", "name", "timezone", "currency" ] }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded unit price before the invoice pricing multiplier." }, "subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Rounded line subtotal after the pricing multiplier, before discounts and tax." }, "taxable": { "type": "boolean" }, "discountable": { "type": "boolean" } }, "required": [ "id", "position", "name", "description", "quantity", "unit_price_cents", "subtotal_cents", "taxable", "discountable" ] }, "InvoiceDiscount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "FLAT", "RATE" ] }, "amount_cents": { "type": "integer", "nullable": true, "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Configured flat discount, null for RATE. Actual combined discount is amounts.discount_cents." }, "rate": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1, "description": "Fraction for RATE; null for FLAT." } }, "required": [ "id", "name", "type", "amount_cents", "rate" ] }, "InvoiceAmounts": { "type": "object", "properties": { "subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "discount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "discounted_subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "paid_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applications of payments whose latest status is PAID." }, "processing_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applications of payments whose latest status is PENDING or PROCESSING." }, "open_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "For OPEN: total minus paid minus processing. Signed, without clamping. Zero for other statuses. Refunds do not automatically reopen this balance." } }, "required": [ "subtotal_cents", "discount_cents", "discounted_subtotal_cents", "tax_cents", "total_cents", "paid_cents", "processing_cents", "open_balance_cents" ] }, "InvoicePaymentApplication": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "applied_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "payment_status": { "allOf": [ { "$ref": "#/components/schemas/NullablePaymentStatus" }, { "description": "Null when no status has been recorded." } ] } }, "required": [ "payment_id", "applied_cents", "payment_status" ], "description": "Identity is (invoice ID, payment_id). Includes unsuccessful/pending applications; only qualifying statuses enter invoice amounts." }, "PaymentInvoiceAllocation": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "applied_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." } }, "required": [ "invoice_id", "applied_cents" ], "description": "Identity is (payment ID, invoice_id). Applications need not consume the entire payment." }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "account": { "$ref": "#/components/schemas/Reference" }, "job_id": { "type": "string", "nullable": true, "format": "uuid" }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "maintenance_plan_id": { "type": "string", "nullable": true, "format": "uuid" }, "business_unit": { "$ref": "#/components/schemas/NullableReference" }, "job_type": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "allOf": [ { "$ref": "#/components/schemas/NullableJobClass" }, { "description": "Recorded job class, including legacy values; not the broader class group." } ] }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update of the underlying parent record only. Child, payment-status, allocation and reference changes may not advance it." }, "issued_at": { "type": "string", "nullable": true, "format": "date-time" }, "due_at": { "type": "string", "nullable": true, "format": "date-time" }, "currency": { "type": "string", "enum": [ "USD" ] }, "pricing_multiplier": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" }, "description": "Complete, ordered by position then ID; also present in collection pages." }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDiscount" }, "description": "Complete ordered discounts." }, "tax": { "type": "object", "properties": { "name": { "type": "string" }, "rate": { "type": "number", "minimum": 0, "maximum": 1 }, "rounding": { "type": "string", "enum": [ "ceil", "round" ] } }, "required": [ "name", "rate", "rounding" ] }, "amounts": { "$ref": "#/components/schemas/InvoiceAmounts" }, "payment_applications": { "type": "array", "items": { "$ref": "#/components/schemas/InvoicePaymentApplication" } }, "aging": { "type": "object", "nullable": true, "properties": { "days_past_due": { "type": "integer", "nullable": true, "description": "Company-local today minus due date; negative before due, null without due date." }, "bucket": { "type": "string", "enum": [ "CURRENT", "PAST_DUE_1_30", "PAST_DUE_31_60", "PAST_DUE_61_90", "PAST_DUE_91_PLUS" ] } }, "required": [ "days_past_due", "bucket" ], "description": "Present only for OPEN invoices. No due date uses CURRENT and null days_past_due." } }, "required": [ "id", "number", "status", "account", "job_id", "location_id", "maintenance_plan_id", "business_unit", "job_type", "job_class", "created_by", "created_at", "updated_at", "issued_at", "due_at", "currency", "pricing_multiplier", "line_items", "discounts", "tax", "amounts", "payment_applications", "aging" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "nullable": true }, "account": { "$ref": "#/components/schemas/Reference" }, "status": { "allOf": [ { "$ref": "#/components/schemas/NullablePaymentStatus" }, { "description": "Null when no status has been recorded; contributes no received amount." } ] }, "method": { "$ref": "#/components/schemas/PaymentMethod" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "currency": { "type": "string", "enum": [ "USD" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Recorded parent edit time, null when unavailable; payment status and allocation changes may not advance it." }, "collected_by": { "$ref": "#/components/schemas/NullableReference" }, "invoice_allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInvoiceAllocation" } } }, "required": [ "id", "number", "account", "status", "method", "amount_cents", "currency", "occurred_at", "created_at", "updated_at", "collected_by", "invoice_allocations" ], "description": "One payment counted once, even if applied to multiple invoices. Occurrence date supports backdating and is not bank settlement." }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid" }, "account": { "$ref": "#/components/schemas/Reference" }, "status": { "$ref": "#/components/schemas/RefundStatus" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "currency": { "type": "string", "enum": [ "USD" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "collected_by": { "allOf": [ { "$ref": "#/components/schemas/NullableReference" }, { "description": "Original payment collector, not refund issuer." } ] } }, "required": [ "id", "payment_id", "account", "status", "amount_cents", "currency", "occurred_at", "created_at", "payment_method", "collected_by" ], "description": "A refund belongs to a payment, not an inferred invoice allocation. Only SUCCEEDED enters refunded collections." }, "SummaryGroup": { "type": "object", "nullable": true, "properties": { "dimension": { "type": "string", "enum": [ "account", "business_unit", "job_type", "job_class", "payment_method", "collector" ] }, "value": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true } }, "required": [ "dimension", "value", "label" ], "description": "Null when ungrouped. For an unknown group the object is present and value/label are null." }, "InvoiceActivityRow": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "group": { "$ref": "#/components/schemas/SummaryGroup" }, "currency": { "type": "string", "enum": [ "USD" ] }, "invoice_count": { "type": "integer", "minimum": 0 }, "subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "discount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "discounted_subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "average_total_cents": { "type": "integer", "nullable": true, "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total / invoice_count, rounded to nearest cent with half-cent ties toward positive infinity (Math.round); null for zero invoices." } }, "required": [ "period_start", "period_end", "group", "currency", "invoice_count", "subtotal_cents", "discount_cents", "discounted_subtotal_cents", "tax_cents", "total_cents", "average_total_cents" ] }, "CollectionsRow": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "group": { "$ref": "#/components/schemas/SummaryGroup" }, "currency": { "type": "string", "enum": [ "USD" ] }, "payment_count": { "type": "integer", "minimum": 0 }, "refund_count": { "type": "integer", "minimum": 0 }, "received_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "refunded_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "net_collections_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." } }, "required": [ "period_start", "period_end", "group", "currency", "payment_count", "refund_count", "received_cents", "refunded_cents", "net_collections_cents" ] }, "ReceivablesAgingRow": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Reference" }, "currency": { "type": "string", "enum": [ "USD" ] }, "invoice_count": { "type": "integer", "minimum": 0 }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "current_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "past_due_1_30_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "past_due_31_60_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "past_due_61_90_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "past_due_91_plus_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." }, "processing_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer USD cents; signed where adjustments or balances permit." } }, "required": [ "account", "currency", "invoice_count", "balance_cents", "current_cents", "past_due_1_30_cents", "past_due_31_60_cents", "past_due_61_90_cents", "past_due_91_plus_cents", "processing_cents" ] }, "CompanyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "InvoiceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "PaymentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "RefundResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Refund" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "InvoicePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "PaymentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "RefundPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "InvoiceActivityResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceActivityRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "bucket": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] }, "group_by": { "type": "string", "nullable": true, "enum": [ "business_unit", "job_type", "job_class", null ] } }, "required": [ "start_date", "end_date", "bucket", "group_by" ] } }, "required": [ "data", "pagination", "meta", "report" ] }, "CollectionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionsRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "bucket": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] }, "group_by": { "type": "string", "nullable": true, "enum": [ "account", "payment_method", "collector", null ] } }, "required": [ "start_date", "end_date", "bucket", "group_by" ] } }, "required": [ "data", "pagination", "meta", "report" ] }, "ReceivablesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivablesAgingRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "aging_date": { "type": "string", "format": "date", "description": "Current company-local date at request time; not a client-selectable as-of date." } }, "required": [ "aging_date" ] } }, "required": [ "data", "pagination", "meta", "report" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_CURSOR", "UNAUTHENTICATED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "RATE_LIMITED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "code", "message", "request_id", "details" ] } }, "required": [ "error" ] }, "Equipment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "hvac_system": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "name" ], "description": "Current HVAC grouping at this same location." }, "equipment_type": { "type": "string", "description": "Recorded type code, including legacy or custom values." }, "status": { "type": "string", "description": "Recorded operational status; usual values are IN_SERVICE, DEACTIVATED, and UNKNOWN." }, "condition": { "type": "string", "nullable": true, "description": "Recorded condition; not an inferred replacement probability." }, "manufacturer": { "type": "string", "nullable": true }, "model_number": { "type": "string", "nullable": true }, "serial_number": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "dimensions": { "type": "string", "nullable": true }, "manufacturing_date": { "type": "string", "nullable": true, "format": "date" }, "installation": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "format": "date" }, "party": { "type": "string", "nullable": true, "description": "Recorded INTERNAL or EXTERNAL installation, including legacy values." } }, "required": [ "date", "party" ] }, "estimated_end_of_life_date": { "type": "string", "nullable": true, "format": "date" }, "average_life_expectancy_years": { "type": "number", "nullable": true }, "manufacturer_warranty": { "type": "object", "properties": { "start_date": { "type": "string", "nullable": true, "format": "date" }, "end_date": { "type": "string", "nullable": true, "format": "date" }, "terms": { "type": "string", "nullable": true } }, "required": [ "start_date", "end_date", "terms" ] }, "labor_warranty": { "type": "object", "properties": { "start_date": { "type": "string", "nullable": true, "format": "date" }, "end_date": { "type": "string", "nullable": true, "format": "date" }, "terms": { "type": "string", "nullable": true } }, "required": [ "start_date", "end_date", "terms" ] }, "created_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Recorded creation time; unavailable on some legacy equipment." }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Equipment-row change only; related system and location changes may not advance it." } }, "required": [ "id", "location_id", "hvac_system", "equipment_type", "status", "condition", "manufacturer", "model_number", "serial_number", "description", "dimensions", "manufacturing_date", "installation", "estimated_end_of_life_date", "average_life_expectancy_years", "manufacturer_warranty", "labor_warranty", "created_at", "updated_at" ], "description": "One installed item at a service location. Dates and warranty terms are recorded inputs, not calculated age, warranty eligibility, or service history." }, "FormResponseQuestion": { "type": "object", "properties": { "question_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Persisted captured question ID when present; not a guaranteed identity across template revisions." }, "answer_path": { "type": "string", "description": "Instance-local JSON pointer into captured content, such as /items/2/left/0/response. Reordering captured questions changes this path." }, "section": { "type": "string", "nullable": true, "description": "Nearest preceding captured section title, if present." }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "CHECKBOX", "TEXT", "PASS_FAIL_FLAG", "YES_NO", "INPUT", "SIGNATURE", "PHOTO" ] }, "required": { "type": "boolean" }, "helper_text": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true, "description": "Recorded string, or null when absent. No, false, 0, and empty strings remain distinct. TEXT HTML is converted to plain text. PHOTO normally stores a CDN URL; SIGNATURE normally stores a PNG data URI. Media strings are not verified attachment references." }, "photo_requirement": { "type": "string", "enum": [ "NONE", "OPTIONAL", "REQUIRED" ] }, "attached_photo_url": { "type": "string", "nullable": true, "description": "Recorded associated-photo string; no media is fetched or signed by this API." } }, "required": [ "question_id", "answer_path", "section", "label", "type", "required", "helper_text", "value", "photo_requirement", "attached_photo_url" ] }, "FormResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "form_id": { "type": "string", "format": "uuid", "description": "Owned source template ID for grouping; current template content is not used to interpret this response." }, "name": { "type": "string", "nullable": true, "description": "Captured form name, not the current template name." }, "instance_number": { "type": "integer", "description": "Recorded instance number, normally a positive ordinal within its appointment and form." }, "label": { "type": "string", "nullable": true }, "ad_hoc": { "type": "boolean" }, "appointment_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "last_edited_by": { "allOf": [ { "$ref": "#/components/schemas/NullableReference" }, { "description": "Recorded last saver, not necessarily the person who answered or completed the form." } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last instance save; saving other forms in the same editor can also advance it. Not an answer-change or completion timestamp." }, "completed": { "type": "boolean", "nullable": true, "description": "Existing required-answer and required-photo check on captured content. Empty or optional-only forms can be complete. Null when the captured structure cannot be interpreted; not a submission or signature verification state." }, "questions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/FormResponseQuestion" }, "description": "Complete captured inputs in display order, including unanswered inputs and both columns. Null when any captured structure is unsupported or malformed; no partial question list is returned." } }, "required": [ "id", "form_id", "name", "instance_number", "label", "ad_hoc", "appointment_id", "job_id", "account_id", "location_id", "last_edited_by", "created_at", "updated_at", "completed", "questions" ] }, "EquipmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Equipment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "EquipmentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Equipment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "FormResponsePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "FormResponseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FormResponse" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "Address": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "formatted": { "type": "string" }, "line_1": { "type": "string" }, "line_2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "id", "formatted", "line_1", "line_2", "city", "state", "postal_code" ] }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "active": { "type": "boolean" }, "deactivated_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "When this member was added to the company." }, "updated_at": { "type": "string", "description": "Unavailable: member profiles and roles have no parent edit timestamp.", "nullable": true, "enum": [ null ] }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Business roles, not API permissions." }, "business_unit_assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "business_unit": { "$ref": "#/components/schemas/Reference" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "nullable": true, "format": "date" } }, "required": [ "id", "business_unit", "start_date", "end_date" ] } } }, "required": [ "id", "name", "first_name", "last_name", "email", "active", "deactivated_at", "created_at", "updated_at", "roles", "business_unit_assignments" ] }, "Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "RESIDENTIAL", "COMMERCIAL" ] }, "customer_since": { "type": "string", "format": "date-time", "description": "Recorded customer-since time, which can predate technical creation after an import." }, "archived": { "type": "boolean" }, "do_not_service": { "type": "boolean" }, "do_not_service_reason": { "type": "string", "nullable": true }, "account_manager": { "$ref": "#/components/schemas/NullableReference" }, "mailing_address": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "formatted": { "type": "string" }, "line_1": { "type": "string" }, "line_2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "id", "formatted", "line_1", "line_2", "city", "state", "postal_code" ] }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contact": { "$ref": "#/components/schemas/Reference" }, "is_primary": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "id", "contact", "is_primary", "archived" ] } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location_id": { "type": "string", "format": "uuid" }, "archived": { "type": "boolean" } }, "required": [ "location_id", "archived" ] } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" } }, "lead_sources": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "Recorded account acquisition sources; separate from job sources." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "id", "number", "name", "type", "customer_since", "archived", "do_not_service", "do_not_service_reason", "account_manager", "mailing_address", "contacts", "locations", "tags", "lead_sources", "created_at", "updated_at" ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "salutation": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "email_addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "address": { "type": "string" }, "usage": { "type": "string", "enum": [ "PRIMARY", "ADDITIONAL" ] } }, "required": [ "id", "address", "usage" ] } }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "type": { "type": "string" }, "usage": { "type": "string", "enum": [ "PRIMARY", "ADDITIONAL" ] } }, "required": [ "id", "number", "type", "usage" ] } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account": { "$ref": "#/components/schemas/Reference" }, "is_primary": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "id", "account", "is_primary", "archived" ] } }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "id", "name", "first_name", "last_name", "salutation", "title", "email_addresses", "phone_numbers", "accounts", "created_by", "created_at", "updated_at" ] }, "Location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/Address" }, "property_type": { "type": "string" }, "municipality": { "type": "string", "nullable": true }, "estimated_square_footage": { "type": "integer", "nullable": true }, "estimated_build_date": { "type": "string", "nullable": true, "format": "date" }, "description": { "type": "string", "nullable": true }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Reference" }, "archived": { "type": "boolean" } }, "required": [ "account", "archived" ] } }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "id", "name", "address", "property_type", "municipality", "estimated_square_footage", "estimated_build_date", "description", "accounts", "created_by", "created_at", "updated_at" ] }, "LifecycleStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "stage": { "type": "string", "enum": [ "Opportunity", "Upcoming", "Ongoing", "Won", "Closed" ] }, "special_status": { "type": "string", "nullable": true, "enum": [ "Canceled", "Closed - Lost", "Completed", null ] }, "is_default": { "type": "boolean" }, "is_work_complete": { "type": "boolean" }, "is_lead_won": { "type": "boolean" } }, "required": [ "id", "name", "description", "stage", "special_status", "is_default", "is_work_complete", "is_lead_won" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "account": { "$ref": "#/components/schemas/Reference" }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "contact": { "$ref": "#/components/schemas/NullableReference" }, "business_unit": { "$ref": "#/components/schemas/NullableReference" }, "job_type": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "$ref": "#/components/schemas/NullableJobClass" }, "lifecycle": { "$ref": "#/components/schemas/NullableReference" }, "status": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "stage": { "type": "string", "enum": [ "Opportunity", "Upcoming", "Ongoing", "Won", "Closed" ] }, "special_status": { "type": "string", "nullable": true, "enum": [ "Canceled", "Closed - Lost", "Completed", null ] }, "is_default": { "type": "boolean" }, "is_work_complete": { "type": "boolean" }, "is_lead_won": { "type": "boolean" } }, "required": [ "id", "name", "description", "stage", "special_status", "is_default", "is_work_complete", "is_lead_won" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "work_completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "lifecycle_closed_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Lifecycle closure; distinct from recorded work completion." }, "outcomes": { "type": "object", "properties": { "is_opportunity": { "type": "boolean" }, "is_converted": { "type": "boolean", "nullable": true }, "is_hot_lead": { "type": "boolean" } }, "required": [ "is_opportunity", "is_converted", "is_hot_lead" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" } }, "lead_sources": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "Sources explicitly linked to this job; no account-source fallback." }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "id", "number", "summary", "account", "location_id", "contact", "business_unit", "job_type", "job_class", "lifecycle", "status", "status_changed_at", "work_completed_at", "lifecycle_closed_at", "outcomes", "tags", "lead_sources", "created_by", "created_at", "updated_at" ] }, "JobAppointment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "description": { "type": "string", "nullable": true }, "window_start_at": { "type": "string", "format": "date-time" }, "window_end_at": { "type": "string", "format": "date-time" }, "confirmed": { "type": "boolean" }, "canceled": { "type": "boolean" }, "cancellation_reason": { "type": "string", "nullable": true }, "cancellation_note": { "type": "string", "nullable": true }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "id", "number", "job_id", "type", "description", "window_start_at", "window_end_at", "confirmed", "canceled", "cancellation_reason", "cancellation_note", "created_by", "created_at", "updated_at" ] }, "JobAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "appointment_id": { "type": "string", "format": "uuid" }, "team_member": { "$ref": "#/components/schemas/Reference" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "nullable": true, "enum": [ "TO_DO", "EN_ROUTE", "IN_PROGRESS", "COMPLETED", "CANCELED", null ] }, "status_updated_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "description": "Unavailable: assignment edits do not maintain a parent update timestamp.", "nullable": true, "enum": [ null ] } }, "required": [ "id", "job_id", "appointment_id", "team_member", "starts_at", "ends_at", "status", "status_updated_at", "created_at", "updated_at" ] }, "BusinessUnit": { "allOf": [ { "$ref": "#/components/schemas/Reference" }, { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "created_at", "updated_at" ] } ] }, "Tag": { "allOf": [ { "$ref": "#/components/schemas/Reference" }, { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "created_at", "updated_at" ] } ] }, "JobType": { "allOf": [ { "$ref": "#/components/schemas/Reference" }, { "type": "object", "properties": { "description": { "type": "string" }, "lifecycle": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "$ref": "#/components/schemas/JobClass" }, "default_business_unit": { "$ref": "#/components/schemas/NullableReference" }, "duration_minutes": { "type": "integer" }, "is_opportunity": { "type": "boolean" }, "archived_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "description", "lifecycle", "job_class", "default_business_unit", "duration_minutes", "is_opportunity", "archived_at", "created_at", "updated_at" ] } ] }, "JobLifecycle": { "allOf": [ { "$ref": "#/components/schemas/Reference" }, { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string", "enum": [ "JOB", "SALES" ] }, "archived": { "type": "boolean" }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/LifecycleStatus" }, "description": "Complete configured sequence, including special-status meanings." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "description", "type", "archived", "statuses", "created_at", "updated_at" ] } ] }, "LeadSource": { "allOf": [ { "$ref": "#/components/schemas/Reference" }, { "type": "object", "properties": { "canonical_name": { "type": "string" }, "archived_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Parent record edit time only; related records may change independently." } }, "required": [ "canonical_name", "archived_at", "created_at", "updated_at" ] } ] }, "JobClassRecord": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/JobClass" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "TeamMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "TeamMemberResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamMember" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "AccountPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "AccountResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "ContactPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "ContactResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "LocationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "LocationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Location" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobAppointmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobAppointment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobAppointmentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobAppointment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobAssignment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobAssignmentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobAssignment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "BusinessUnitPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessUnit" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "BusinessUnitResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessUnit" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobTypePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobType" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobType" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobClassPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobClassRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobClassResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobClassRecord" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobLifecyclePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobLifecycle" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobLifecycleResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobLifecycle" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "LeadSourcePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadSource" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "LeadSourceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadSource" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "TagPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "TagResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "EstimateStatus": { "type": "string", "enum": [ "DRAFT", "CREATED", "SENT", "REVIEWED", "ACCEPTED", "VOIDED", "CLOSED", "EXPIRED" ] }, "JobLeadStatus": { "type": "string", "enum": [ "open", "converted", "archived" ] }, "EstimateLineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "description": "Recorded ordering position; ties are ordered by ID." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true, "description": "Recorded line description as plain text." }, "item_type": { "type": "string" }, "code": { "type": "string", "nullable": true }, "variant": { "type": "string", "nullable": true }, "pricebook_item_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Optional catalog provenance; prices and descriptions are snapshots." }, "quantity": { "type": "number" }, "unit_price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded unit price before the presentation/conversion pricing multiplier." }, "taxable": { "type": "boolean" }, "discountable": { "type": "boolean" } }, "required": [ "id", "position", "name", "description", "item_type", "code", "variant", "pricebook_item_id", "quantity", "unit_price_cents", "taxable", "discountable" ] }, "EstimateDiscount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "description": "Recorded ordering position; ties are ordered by ID." }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "FLAT", "RATE" ] }, "amount_cents": { "type": "integer", "nullable": true, "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Configured amount for FLAT; null for RATE." }, "rate": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1, "description": "Configured fractional rate for RATE; null for FLAT." } }, "required": [ "id", "position", "name", "description", "type", "amount_cents", "rate" ] }, "EstimateOption": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "description": "Recorded ordering position; ties are ordered by ID." }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "selected": { "type": "boolean" }, "recommended": { "type": "boolean" }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Current recorded option total. Not recalculated from current invoice rules or catalog prices; alternatives are not additive." }, "tax_rounding": { "type": "string", "enum": [ "ceil", "round" ], "description": "Company configuration at option creation, using the application fallback of ceil when unavailable." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/EstimateLineItem" }, "description": "Complete ordered lines, also included in collection pages." }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/EstimateDiscount" }, "description": "Complete ordered configured discounts." } }, "required": [ "id", "position", "name", "description", "selected", "recommended", "total_cents", "tax_rounding", "line_items", "discounts" ] }, "Estimate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/EstimateStatus" }, "account": { "$ref": "#/components/schemas/Reference" }, "job_id": { "type": "string", "format": "uuid", "description": "Original proposal job; a resulting invoice can belong to another linked job." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "job_appointment_id": { "type": "string", "nullable": true, "format": "uuid" }, "business_unit": { "$ref": "#/components/schemas/NullableReference" }, "job_type": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "$ref": "#/components/schemas/NullableJobClass" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/NullableReference" }, { "description": "Recorded estimate creator, not an inferred seller." } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last parent-record edit only. Child and relationship edits may not advance it; not a complete change feed." }, "accepted_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Recorded acceptance time, which can remain after reopening." }, "accepted_on_behalf_by": { "allOf": [ { "$ref": "#/components/schemas/NullableReference" }, { "description": "Recorded staff acceptance proxy; not necessarily the current signer or seller, and not a signing history." } ] }, "last_sent_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Recorded latest send attempt; does not prove delivery." }, "message": { "type": "string", "nullable": true, "description": "Canonical proposal message as plain text." }, "closed_lost_reason": { "type": "object", "properties": { "category": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "category", "note" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "pricing_multiplier": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Presentation/conversion multiplier from the recorded pricing setting. Recorded option totals are preserved, not recomputed using this multiplier." }, "tax": { "type": "object", "properties": { "name": { "type": "string" }, "rate": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "name", "rate" ] }, "accepted_total_cents": { "type": "integer", "nullable": true, "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Current recorded total of exactly one selected option when status is ACCEPTED; otherwise null. Not a frozen acceptance-time amount." }, "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "All tenant-owned resulting invoice IDs, ordered by ID. Lines are copied on conversion." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/EstimateOption" }, "description": "Complete alternatives ordered by position then ID; never sum them as estimate value." } }, "required": [ "id", "number", "status", "account", "job_id", "location_id", "job_appointment_id", "business_unit", "job_type", "job_class", "created_by", "created_at", "updated_at", "accepted_at", "accepted_on_behalf_by", "last_sent_at", "message", "closed_lost_reason", "currency", "pricing_multiplier", "tax", "accepted_total_cents", "invoice_ids", "options" ] }, "JobLead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "allOf": [ { "$ref": "#/components/schemas/JobLeadStatus" }, { "description": "Recorded intake state. Converted does not mean sold or paid." } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last parent-record edit only. Child and relationship edits may not advance it; not a complete change feed." }, "summary": { "type": "string", "nullable": true }, "request_type": { "type": "string", "nullable": true, "description": "Recorded service-request category; legacy values are retained." }, "submitted_account_type": { "type": "string", "nullable": true, "description": "Captured customer-type text; not the current account classification." }, "submitted_service_type": { "type": "string", "nullable": true, "description": "Legacy submitted service-type text, separate from configured job types." }, "submitted_job_type": { "$ref": "#/components/schemas/NullableReference" }, "source_text": { "type": "string", "nullable": true, "description": "Free-form intake source text, not a configured lead-source ID or inferred attribution." }, "contact": { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true } }, "required": [ "first_name", "last_name", "email_address", "phone_number" ] }, "service_address": { "type": "object", "properties": { "line_1": { "type": "string", "nullable": true }, "line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true } }, "required": [ "line_1", "line_2", "city", "state", "postal_code" ] }, "existing_location_id": { "type": "string", "nullable": true, "format": "uuid" }, "job_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Recorded converted-job link. Multiple leads can link to one job; no conversion timestamp is stored." } }, "required": [ "id", "status", "created_at", "updated_at", "summary", "request_type", "submitted_account_type", "submitted_service_type", "submitted_job_type", "source_text", "contact", "service_address", "existing_location_id", "job_id" ], "description": "Submitted request and captured contact/address values. These are not enriched from current CRM records." }, "EstimatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Estimate" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "EstimateResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Estimate" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobLeadPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobLead" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobLeadResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobLead" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "TimeEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_member": { "$ref": "#/components/schemas/Reference" }, "starts_at": { "type": "string", "format": "date-time", "description": "Effective start: recorded correction when present, otherwise original start." }, "ends_at": { "type": "string", "nullable": true, "format": "date-time", "description": "Effective end; null means the entry remains open." }, "start_corrected": { "type": "boolean" }, "end_corrected": { "type": "boolean" }, "duration_minutes": { "type": "number", "nullable": true, "description": "Elapsed effective minutes, including fractions and overnight time; null for open entries. Not capped timesheet payable minutes." }, "activity": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "Recorded name, including custom activity names." }, "kind": { "type": "string", "enum": [ "IDLE", "DRIVE-TIME", "ON-SITE", "LUNCH", "CUSTOM" ] } }, "required": [ "name", "kind" ], "description": "Null when a single company-owned activity cannot be established." }, "payable": { "type": "boolean", "nullable": true, "description": "Recorded payable flag, independent of activity name; null when activity is unavailable or ambiguous." }, "job_id": { "type": "string", "nullable": true, "format": "uuid" }, "appointment_id": { "type": "string", "nullable": true, "format": "uuid" }, "assignment_id": { "type": "string", "nullable": true, "format": "uuid" }, "attention_note": { "type": "string", "nullable": true }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/NullableReference" }, "updated_by": { "$ref": "#/components/schemas/NullableReference" }, "deleted_by": { "$ref": "#/components/schemas/NullableReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "description": "Unavailable: existing entry edits and work-link changes do not reliably maintain a modification timestamp. Refresh bounded effective-start windows.", "nullable": true, "enum": [ null ] } }, "required": [ "id", "team_member", "starts_at", "ends_at", "start_corrected", "end_corrected", "duration_minutes", "activity", "payable", "job_id", "appointment_id", "assignment_id", "attention_note", "deleted_at", "created_by", "updated_by", "deleted_by", "created_at", "updated_at" ] }, "TimeEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "TimeEntryResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimeEntry" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "TimesheetPeriod": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Inclusive company-local date under the current configured pay period." }, "end_date_exclusive": { "type": "string", "format": "date", "description": "Exclusive company-local date. Select this date as period_date to retrieve the next period." } }, "required": [ "start_date", "end_date_exclusive" ] }, "Timesheet": { "type": "object", "properties": { "team_member": { "$ref": "#/components/schemas/Reference" }, "period": { "$ref": "#/components/schemas/TimesheetPeriod" }, "entry_count": { "type": "integer", "minimum": 0, "description": "Nondeleted entries whose effective start falls in this period, including open and nonpayable entries." }, "open_entry_count": { "type": "integer", "minimum": 0 }, "unknown_activity_entry_count": { "type": "integer", "minimum": 0, "description": "Entries without one unambiguous owned activity; excluded from payable totals." }, "payable_minutes": { "type": "integer", "minimum": 0, "description": "Sum of daily payable minutes using existing timesheet rules; not payroll, overtime, or raw elapsed time." }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "payable_minutes": { "type": "integer", "minimum": 0, "maximum": 1439 } }, "required": [ "date", "payable_minutes" ] }, "description": "Every local date in the period, including zero-minute days. Closed, payable, nondeleted entries only; whole wall-clock minutes using the existing server timesheet calculation (including its daylight-saving behavior), capped at 1439 per day. Overnight entries stop at the end of their start day." } }, "required": [ "team_member", "period", "entry_count", "open_entry_count", "unknown_activity_entry_count", "payable_minutes", "days" ], "description": "A derived member-period representation, identified by member ID and resolved period dates. No persisted ID or modification timestamp. Includes inactive and zero-entry current company members of every role." }, "TimesheetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Timesheet" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "TimesheetResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Timesheet" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "ProfitabilityTotals": { "type": "object", "properties": { "revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded pre-discount, pre-tax invoice subtotals in OPEN, PAID or UNCOLLECTABLE status." }, "labor_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parts_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "equipment_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "misc_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "other_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded costs with an unrecognized category; retained in total costs." }, "total_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_profit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_margin": { "type": "number", "nullable": true, "description": "Gross profit / revenue, rounded to four decimal places; null at zero revenue. A fraction, not a percentage." } }, "required": [ "revenue_cents", "labor_cost_cents", "parts_cost_cents", "equipment_cost_cents", "misc_cost_cents", "other_cost_cents", "total_cost_cents", "gross_profit_cents", "gross_margin" ] }, "JobCostEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "description": "Recorded category, normally labor, parts, equipment or misc; legacy values are preserved." }, "source": { "type": "string", "description": "Recorded source, normally manual, timesheet or invoice. This does not identify a worker or allocate revenue." }, "name": { "type": "string" }, "quantity": { "type": "number" }, "quantity_unit": { "type": "string", "enum": [ "minute", "unit" ] }, "unit_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded hourly cost for labor; per-unit cost for other categories." }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "PostgreSQL numeric rounding per entry: quantity / 60 × hourly cost for labor, quantity × unit cost otherwise. Half-cent ties round away from zero." }, "labor_activity": { "type": "string", "nullable": true }, "misc_category": { "$ref": "#/components/schemas/NullableReference" }, "pricebook_item_id": { "type": "string", "nullable": true, "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "category", "source", "name", "quantity", "quantity_unit", "unit_cost_cents", "total_cents", "labor_activity", "misc_category", "pricebook_item_id", "created_at", "updated_at" ] }, "JobFinancials": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The job ID; this resource has no separate persisted identity." }, "number": { "type": "string" }, "account": { "$ref": "#/components/schemas/Reference" }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "business_unit": { "$ref": "#/components/schemas/NullableReference" }, "job_type": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "$ref": "#/components/schemas/NullableJobClass" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "Distinct currently associated company members with retained, consistently linked assignments. Includes inactive members and canceled visits; assignment is not proof of attendance." }, "created_at": { "type": "string", "format": "date-time", "description": "Job creation time, not creation of a financial snapshot." }, "report_date": { "type": "string", "format": "date", "description": "Company-local date of the earliest qualifying invoice issue time, otherwise job work completion, otherwise job creation. All job revenue and recorded costs use this date." }, "report_date_basis": { "type": "string", "enum": [ "INVOICE_ISSUED", "WORK_COMPLETED", "JOB_CREATED" ] }, "costing": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tracking_status": { "type": "string" }, "verification_status": { "type": "string", "description": "Recorded current verification state; no verifier or verification timestamp is implied." }, "job_type_included": { "type": "boolean", "nullable": true, "description": "Current job-type costing inclusion; null when the owned type is unavailable." } }, "required": [ "enabled", "tracking_status", "verification_status", "job_type_included" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "totals": { "type": "object", "nullable": true, "properties": { "revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded pre-discount, pre-tax invoice subtotals in OPEN, PAID or UNCOLLECTABLE status." }, "labor_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parts_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "equipment_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "misc_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "other_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded costs with an unrecognized category; retained in total costs." }, "total_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_profit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_margin": { "type": "number", "nullable": true, "description": "Gross profit / revenue, rounded to four decimal places; null at zero revenue. A fraction, not a percentage." } }, "required": [ "revenue_cents", "labor_cost_cents", "parts_cost_cents", "equipment_cost_cents", "misc_cost_cents", "other_cost_cents", "total_cost_cents", "gross_profit_cents", "gross_margin" ], "description": "Unavailable when company costing is disabled or the job is not TRACKED. Saved entries and invoice facts remain readable. Unverified or excluded tracked jobs retain calculations." }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "PAID", "UNCOLLECTABLE" ] }, "issued_at": { "type": "string", "nullable": true, "format": "date-time" }, "subtotal_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "number", "status", "issued_at", "subtotal_cents" ] }, "description": "Complete owned qualifying invoice facts; their recorded subtotals explain the costing revenue basis." }, "cost_entries": { "type": "array", "items": { "$ref": "#/components/schemas/JobCostEntry" }, "description": "Complete saved cost entries. Reads never populate or synchronize costs from time entries, wages, invoice lines or pricebook data." } }, "required": [ "id", "number", "account", "location_id", "business_unit", "job_type", "job_class", "participants", "created_at", "report_date", "report_date_basis", "costing", "currency", "totals", "invoices", "cost_entries" ] }, "JobProfitabilityRow": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "USD" ] }, "group": { "type": "object", "nullable": true, "properties": { "dimension": { "type": "string", "enum": [ "business_unit", "job_type", "job_class" ] }, "value": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true } }, "required": [ "dimension", "value", "label" ] }, "job_count": { "type": "integer", "minimum": 0 }, "revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded pre-discount, pre-tax invoice subtotals in OPEN, PAID or UNCOLLECTABLE status." }, "labor_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parts_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "equipment_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "misc_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "other_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded costs with an unrecognized category; retained in total costs." }, "total_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_profit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_margin": { "type": "number", "nullable": true, "description": "Gross profit / revenue, rounded to four decimal places; null at zero revenue. A fraction, not a percentage." } }, "required": [ "period_start", "period_end", "currency", "group", "job_count", "revenue_cents", "labor_cost_cents", "parts_cost_cents", "equipment_cost_cents", "misc_cost_cents", "other_cost_cents", "total_cost_cents", "gross_profit_cents", "gross_margin" ] }, "TechnicianParticipationRow": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "USD" ] }, "group": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "team_member" ] }, "value": { "type": "string", "format": "uuid" }, "label": { "type": "string" } }, "required": [ "dimension", "value", "label" ] }, "job_count": { "type": "integer", "minimum": 0 }, "revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded pre-discount, pre-tax invoice subtotals in OPEN, PAID or UNCOLLECTABLE status." }, "labor_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parts_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "equipment_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "misc_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "other_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Recorded costs with an unrecognized category; retained in total costs." }, "total_cost_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_profit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "gross_margin": { "type": "number", "nullable": true, "description": "Gross profit / revenue, rounded to four decimal places; null at zero revenue. A fraction, not a percentage." } }, "required": [ "period_start", "period_end", "currency", "group", "job_count", "revenue_cents", "labor_cost_cents", "parts_cost_cents", "equipment_cost_cents", "misc_cost_cents", "other_cost_cents", "total_cost_cents", "gross_profit_cents", "gross_margin" ], "description": "Each distinct assigned member receives the whole included job result once. Member rows overlap; do not sum them as company totals. Jobs without participants have no member row." }, "JobFinancialsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobFinancials" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "JobFinancialsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobFinancials" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "JobProfitabilityResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobProfitabilityRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "end_date": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "bucket": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "costing_enabled": { "type": "boolean", "description": "False means this company has no enabled costing configuration; report rows are empty, not zero-valued profitability." }, "verified_only": { "type": "boolean" }, "include_excluded_job_types": { "type": "boolean" }, "group_by": { "type": "string", "nullable": true, "enum": [ "business_unit", "job_type", "job_class", null ] } }, "required": [ "start_date", "end_date", "costing_enabled", "verified_only", "include_excluded_job_types" ] } }, "required": [ "data", "pagination", "meta", "report" ] }, "TechnicianParticipationResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TechnicianParticipationRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "end_date": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "bucket": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "costing_enabled": { "type": "boolean", "description": "False means this company has no enabled costing configuration; report rows are empty, not zero-valued profitability." }, "verified_only": { "type": "boolean" }, "include_excluded_job_types": { "type": "boolean" }, "group_by": { "type": "string", "enum": [ "team_member" ] } }, "required": [ "start_date", "end_date", "costing_enabled", "verified_only", "include_excluded_job_types", "group_by" ] } }, "required": [ "data", "pagination", "meta", "report" ] }, "RevenueCredit": { "type": "object", "properties": { "credit_type": { "type": "string", "enum": [ "SOLD", "EARNED" ] }, "revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The saved signed credit, including zero. Never recalculated from current invoice lines or divided among people." }, "team_member": { "allOf": [ { "$ref": "#/components/schemas/NullableReference" }, { "description": "Current company member, including inactive and non-technician members; null if unavailable. The saved amount remains included." } ] }, "invoice": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" } }, "required": [ "id", "number" ], "description": "Currently owned invoice linked to this job with an owned account, regardless of status; null when unavailable." }, "invoice_line_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Current owned lines on the validated invoice matching the saved cart-item key or owned original pricebook key. Several lines may match. Context only: count the credit once, never once per matching line. Empty when unavailable." } }, "required": [ "credit_type", "revenue_cents", "team_member", "invoice", "invoice_line_item_ids" ] }, "RevenueAttributions": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Job ID. Replace this job’s complete credit array when refreshing it; credits have no public row IDs." }, "number": { "type": "string" }, "account": { "$ref": "#/components/schemas/Reference" }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "business_unit": { "$ref": "#/components/schemas/NullableReference" }, "job_type": { "$ref": "#/components/schemas/NullableReference" }, "job_class": { "$ref": "#/components/schemas/NullableJobClass" }, "created_at": { "type": "string", "format": "date-time", "description": "Job creation time, not the time its credits were saved." }, "work_completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "report_date": { "type": "string", "nullable": true, "format": "date", "description": "Company-local work-completion date, without fallback. Undated jobs remain readable but do not enter dated summaries." }, "currency": { "type": "string", "enum": [ "USD" ] }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueCredit" }, "description": "Complete saved sold and earned credits. Empty means none recorded. Each member may receive the full amount independently, so credits overlap. Sold and earned are separate measures, not additive company revenue. Identical-looking credits with unavailable links remain separate." } }, "required": [ "id", "number", "account", "location_id", "business_unit", "job_type", "job_class", "created_at", "work_completed_at", "report_date", "currency", "credits" ] }, "RevenueAttributionRow": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "USD" ] }, "group": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "team_member" ] }, "value": { "type": "string", "nullable": true, "format": "uuid" }, "label": { "type": "string", "nullable": true } }, "required": [ "dimension", "value", "label" ], "description": "Null value and label retain credits for unavailable members and may combine several people." }, "job_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Distinct jobs with at least one contributing credit after filters, including zero-valued credits." }, "sold_credit_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "earned_credit_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sold_revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "earned_revenue_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "period_start", "period_end", "currency", "group", "job_count", "sold_credit_count", "earned_credit_count", "sold_revenue_cents", "earned_revenue_cents" ] }, "RevenueAttributionsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueAttributions" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "pagination", "meta" ] }, "RevenueAttributionsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RevenueAttributions" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ] }, "RevenueAttributionReportResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueAttributionRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "report": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "end_date": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "bucket": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "group_by": { "type": "string", "enum": [ "team_member" ] }, "date_basis": { "type": "string", "enum": [ "WORK_COMPLETED" ] } }, "required": [ "start_date", "end_date", "group_by", "date_basis" ] } }, "required": [ "data", "pagination", "meta", "report" ] } }, "parameters": {} }, "paths": { "/company": { "get": { "operationId": "getCompany", "tags": [ "Company" ], "summary": "Read the company associated with this key", "description": "Read only within the company associated with the validated key.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000001", "name": "Example Heating & Air", "timezone": "America/Los_Angeles", "currency": "USD" }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/invoices": { "get": { "operationId": "listInvoices", "tags": [ "Invoices" ], "summary": "Page complete invoices", "description": "All statuses by default. Orders by created_at then id ascending. Lines, discounts and payment applications are complete on every page. Amounts use the public invoice calculator; refunds are not inferred as invoice-level allocations.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/InvoiceStatus" }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Inclusive company-local issue date." }, "required": false, "description": "Inclusive company-local issue date.", "name": "issued_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Exclusive company-local issue date." }, "required": false, "description": "Exclusive company-local issue date.", "name": "issued_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000601", "number": "1001", "status": "OPEN", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "job_id": "11111111-1111-4111-8111-000000000501", "location_id": null, "maintenance_plan_id": null, "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-20T16:00:00Z", "updated_at": "2026-08-20T16:00:00Z", "issued_at": "2026-08-20T16:00:00Z", "due_at": "2026-08-31T07:00:00Z", "currency": "USD", "pricing_multiplier": 1, "line_items": [ { "id": "11111111-1111-4111-8111-000000000901", "position": 1, "name": "HVAC repair", "description": "HVAC repair", "quantity": 1, "unit_price_cents": 100000, "subtotal_cents": 100000, "taxable": true, "discountable": true } ], "discounts": [ { "id": "11111111-1111-4111-8111-000000000911", "name": "Service discount", "type": "FLAT", "amount_cents": 10000, "rate": null } ], "tax": { "name": "Sales tax", "rate": 0.1, "rounding": "round" }, "amounts": { "subtotal_cents": 100000, "discount_cents": 10000, "discounted_subtotal_cents": 90000, "tax_cents": 9000, "total_cents": 99000, "paid_cents": 50000, "processing_cents": 10000, "open_balance_cents": 39000 }, "payment_applications": [ { "payment_id": "11111111-1111-4111-8111-000000000701", "applied_cents": 50000, "payment_status": "PAID" }, { "payment_id": "11111111-1111-4111-8111-000000000702", "applied_cents": 10000, "payment_status": "PROCESSING" } ], "aging": { "days_past_due": 8, "bucket": "PAST_DUE_1_30" } }, { "id": "11111111-1111-4111-8111-000000000602", "number": "1002", "status": "PAID", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "job_id": "11111111-1111-4111-8111-000000000501", "location_id": null, "maintenance_plan_id": null, "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-09-02T16:00:00Z", "updated_at": "2026-09-02T18:00:00Z", "issued_at": "2026-09-02T16:00:00Z", "due_at": "2026-09-02T07:00:00Z", "currency": "USD", "pricing_multiplier": 1, "line_items": [ { "id": "11111111-1111-4111-8111-000000000902", "position": 1, "name": "Additional service", "description": "Additional service", "quantity": 1, "unit_price_cents": 30000, "subtotal_cents": 30000, "taxable": false, "discountable": true } ], "discounts": [], "tax": { "name": "Sales tax", "rate": 0, "rounding": "round" }, "amounts": { "subtotal_cents": 30000, "discount_cents": 0, "discounted_subtotal_cents": 30000, "tax_cents": 0, "total_cents": 30000, "paid_cents": 30000, "processing_cents": 0, "open_balance_cents": 0 }, "payment_applications": [ { "payment_id": "11111111-1111-4111-8111-000000000701", "applied_cents": 30000, "payment_status": "PAID" } ], "aging": null } ], "pagination": { "next_cursor": "example-opaque-cursor" }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/invoices/{invoice_id}": { "get": { "operationId": "getInvoice", "tags": [ "Invoices" ], "summary": "Read one complete invoice", "description": "Read only within the company associated with the validated key.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "invoice_id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000601", "number": "1001", "status": "OPEN", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "job_id": "11111111-1111-4111-8111-000000000501", "location_id": null, "maintenance_plan_id": null, "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-20T16:00:00Z", "updated_at": "2026-08-20T16:00:00Z", "issued_at": "2026-08-20T16:00:00Z", "due_at": "2026-08-31T07:00:00Z", "currency": "USD", "pricing_multiplier": 1, "line_items": [ { "id": "11111111-1111-4111-8111-000000000901", "position": 1, "name": "HVAC repair", "description": "HVAC repair", "quantity": 1, "unit_price_cents": 100000, "subtotal_cents": 100000, "taxable": true, "discountable": true } ], "discounts": [ { "id": "11111111-1111-4111-8111-000000000911", "name": "Service discount", "type": "FLAT", "amount_cents": 10000, "rate": null } ], "tax": { "name": "Sales tax", "rate": 0.1, "rounding": "round" }, "amounts": { "subtotal_cents": 100000, "discount_cents": 10000, "discounted_subtotal_cents": 90000, "tax_cents": 9000, "total_cents": 99000, "paid_cents": 50000, "processing_cents": 10000, "open_balance_cents": 39000 }, "payment_applications": [ { "payment_id": "11111111-1111-4111-8111-000000000701", "applied_cents": 50000, "payment_status": "PAID" }, { "payment_id": "11111111-1111-4111-8111-000000000702", "applied_cents": 10000, "payment_status": "PROCESSING" } ], "aging": { "days_past_due": 8, "bucket": "PAST_DUE_1_30" } }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/payments": { "get": { "operationId": "listPayments", "tags": [ "Payments" ], "summary": "Page payments with their invoice allocations", "description": "All statuses by default. Orders by created_at then id ascending. A payment amount is counted once regardless of its invoice allocations.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PaymentStatus" }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "CARD", "ACH", "CASH", "CHECK", "PAYPAL", "VENMO", "CASHAPP", "OTHER", "WISETACK_LOAN", null ] }, "required": false, "name": "method", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "collected_by_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "occurred_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "occurred_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000701", "number": "P-1001", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "PAID", "method": "CARD", "amount_cents": 80000, "currency": "USD", "occurred_at": "2026-09-02T18:00:00Z", "created_at": "2026-09-02T18:00:00Z", "updated_at": "2026-09-02T18:00:00Z", "collected_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice_allocations": [ { "invoice_id": "11111111-1111-4111-8111-000000000601", "applied_cents": 50000 }, { "invoice_id": "11111111-1111-4111-8111-000000000602", "applied_cents": 30000 } ] }, { "id": "11111111-1111-4111-8111-000000000702", "number": "P-1002", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "PROCESSING", "method": "ACH", "amount_cents": 10000, "currency": "USD", "occurred_at": "2026-09-07T18:00:00Z", "created_at": "2026-09-07T18:00:00Z", "updated_at": null, "collected_by": null, "invoice_allocations": [ { "invoice_id": "11111111-1111-4111-8111-000000000601", "applied_cents": 10000 } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/payments/{payment_id}": { "get": { "operationId": "getPayment", "tags": [ "Payments" ], "summary": "Read one payment", "description": "Read only within the company associated with the validated key.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "payment_id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000701", "number": "P-1001", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "PAID", "method": "CARD", "amount_cents": 80000, "currency": "USD", "occurred_at": "2026-09-02T18:00:00Z", "created_at": "2026-09-02T18:00:00Z", "updated_at": "2026-09-02T18:00:00Z", "collected_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice_allocations": [ { "invoice_id": "11111111-1111-4111-8111-000000000601", "applied_cents": 50000 }, { "invoice_id": "11111111-1111-4111-8111-000000000602", "applied_cents": 30000 } ] }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/refunds": { "get": { "operationId": "listRefunds", "tags": [ "Refunds" ], "summary": "Page refunds using their own occurrence dates", "description": "All statuses by default. Orders by created_at then id ascending. Date filters refer to this refund, even if its payment occurred in an earlier period.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "payment_id", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RefundStatus" }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "CARD", "ACH", "CASH", "CHECK", "PAYPAL", "VENMO", "CASHAPP", "OTHER", "WISETACK_LOAN", null ] }, "required": false, "name": "payment_method", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "collected_by_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "occurred_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "occurred_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000801", "payment_id": "11111111-1111-4111-8111-000000000701", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "SUCCEEDED", "amount_cents": 5000, "currency": "USD", "occurred_at": "2026-09-06T18:00:00Z", "created_at": "2026-09-06T18:00:00Z", "payment_method": "CARD", "collected_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" } }, { "id": "11111111-1111-4111-8111-000000000802", "payment_id": "11111111-1111-4111-8111-000000000701", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "PENDING", "amount_cents": 2000, "currency": "USD", "occurred_at": "2026-09-07T18:30:00Z", "created_at": "2026-09-07T18:30:00Z", "payment_method": "CARD", "collected_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" } } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/refunds/{refund_id}": { "get": { "operationId": "getRefund", "tags": [ "Refunds" ], "summary": "Read one refund", "description": "Read only within the company associated with the validated key.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "refund_id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000801", "payment_id": "11111111-1111-4111-8111-000000000701", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "status": "SUCCEEDED", "amount_cents": 5000, "currency": "USD", "occurred_at": "2026-09-06T18:00:00Z", "created_at": "2026-09-06T18:00:00Z", "payment_method": "CARD", "collected_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" } }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/invoice-activity": { "get": { "operationId": "getInvoiceActivity", "tags": [ "Reports" ], "summary": "Summarize invoice activity by issue date", "description": "Defaults to OPEN and PAID invoices whose issued_at falls within the company-local date range. Sum public invoice amounts. One optional business grouping plus time. Null issue dates are excluded. Rows order by period_start then group value (null first); empty groups/buckets are omitted.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "required": true, "description": "Inclusive company-local date.", "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "required": true, "description": "Exclusive company-local date; must be after start_date.", "name": "end_date", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "required": false, "name": "bucket", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceStatus" }, "minItems": 1, "default": [ "OPEN", "PAID" ] }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "business_unit", "job_type", "job_class", null ] }, "required": false, "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceActivityResponse" }, "example": { "data": [ { "period_start": "2026-08-01", "period_end": "2026-09-01", "group": null, "currency": "USD", "invoice_count": 1, "subtotal_cents": 100000, "discount_cents": 10000, "discounted_subtotal_cents": 90000, "tax_cents": 9000, "total_cents": 99000, "average_total_cents": 99000 }, { "period_start": "2026-09-01", "period_end": "2026-10-01", "group": null, "currency": "USD", "invoice_count": 2, "subtotal_cents": 50000, "discount_cents": 0, "discounted_subtotal_cents": 50000, "tax_cents": 0, "total_cents": 50000, "average_total_cents": 25000 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "start_date": "2026-08-01", "end_date": "2026-10-01", "bucket": "month", "group_by": null } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/collections": { "get": { "operationId": "getCollections", "tags": [ "Reports" ], "summary": "Summarize successful payments and refunds", "description": "PAID payments minus SUCCEEDED refunds; each uses its own occurrence date and is counted once. No proportional refund allocation to invoices, jobs or business units. One optional grouping plus time; rows order by period_start then group value (null first). Empty groups/buckets are omitted.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "required": true, "description": "Inclusive company-local date.", "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "required": true, "description": "Exclusive company-local date; must be after start_date.", "name": "end_date", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "required": false, "name": "bucket", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "CARD", "ACH", "CASH", "CHECK", "PAYPAL", "VENMO", "CASHAPP", "OTHER", "WISETACK_LOAN", null ] }, "required": false, "name": "method", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "collected_by_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "account", "payment_method", "collector", null ] }, "required": false, "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionsResponse" }, "example": { "data": [ { "period_start": "2026-09-01", "period_end": "2026-10-01", "group": null, "currency": "USD", "payment_count": 1, "refund_count": 1, "received_cents": 80000, "refunded_cents": 5000, "net_collections_cents": 75000 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "start_date": "2026-09-01", "end_date": "2026-10-01", "bucket": "month", "group_by": null } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/receivables-aging": { "get": { "operationId": "getReceivablesAging", "tags": [ "Reports" ], "summary": "Read current account aging", "description": "OPEN invoices only, including zero/negative balances. Group by account ID ascending. Signed buckets sum to balance_cents. Aging uses current company-local date; no as_of or historical date range. Accounts without qualifying OPEN invoices are omitted. Drill down with the identical filters on GET /invoices?status=OPEN.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesResponse" }, "example": { "data": [ { "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "currency": "USD", "invoice_count": 2, "balance_cents": 59000, "current_cents": 20000, "past_due_1_30_cents": 39000, "past_due_31_60_cents": 0, "past_due_61_90_cents": 0, "past_due_91_plus_cents": 0, "processing_cents": 10000 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "example-request", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "aging_date": "2026-09-08" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/team-members": { "get": { "operationId": "listTeamMembers", "tags": [ "TeamMembers" ], "summary": "Page team members", "description": "Company members, including inactive members, with business roles and dated business-unit assignments. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Exact business role ID from roles[].id, for example SERVICE_TECHNICIAN; not its display name." }, "required": false, "description": "Exact business role ID from roles[].id, for example SERVICE_TECHNICIAN; not its display name.", "name": "role", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "active", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example", "first_name": "Alex", "last_name": "Example", "email": "alex@example.invalid", "active": true, "deactivated_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": null, "roles": [ { "id": "SERVICE_TECHNICIAN", "name": "Service Tech" } ], "business_unit_assignments": [ { "id": "11111111-1111-4111-8111-000000001110", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "start_date": "2026-01-01", "end_date": null } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/team-members/{id}": { "get": { "operationId": "getTeamMember", "tags": [ "TeamMembers" ], "summary": "Read one team member", "description": "Company members, including inactive members, with business roles and dated business-unit assignments.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example", "first_name": "Alex", "last_name": "Example", "email": "alex@example.invalid", "active": true, "deactivated_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": null, "roles": [ { "id": "SERVICE_TECHNICIAN", "name": "Service Tech" } ], "business_unit_assignments": [ { "id": "11111111-1111-4111-8111-000000001110", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "start_date": "2026-01-01", "end_date": null } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/accounts": { "get": { "operationId": "listAccounts", "tags": [ "Accounts" ], "summary": "Page accounts", "description": "Customers with complete contact/location associations, tags, and recorded acquisition sources. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "RESIDENTIAL", "COMMERCIAL", null ] }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "archived", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "contact_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household", "number": "100", "customer_since": "2018-03-10T23:59:59.123456Z", "type": "RESIDENTIAL", "archived": false, "do_not_service": false, "do_not_service_reason": null, "account_manager": null, "mailing_address": { "id": "11111111-1111-4111-8111-000000001104", "formatted": "123 Example Lane, Los Angeles, CA 90001", "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "contacts": [ { "id": "11111111-1111-4111-8111-000000001108", "contact": { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example" }, "is_primary": true, "archived": false } ], "locations": [ { "location_id": "11111111-1111-4111-8111-000000001107", "archived": false } ], "tags": [ { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer" } ], "lead_sources": [ { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral" } ], "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/accounts/{id}": { "get": { "operationId": "getAccount", "tags": [ "Accounts" ], "summary": "Read one account", "description": "Customers with complete contact/location associations, tags, and recorded acquisition sources.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household", "number": "100", "customer_since": "2018-03-10T23:59:59.123456Z", "type": "RESIDENTIAL", "archived": false, "do_not_service": false, "do_not_service_reason": null, "account_manager": null, "mailing_address": { "id": "11111111-1111-4111-8111-000000001104", "formatted": "123 Example Lane, Los Angeles, CA 90001", "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "contacts": [ { "id": "11111111-1111-4111-8111-000000001108", "contact": { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example" }, "is_primary": true, "archived": false } ], "locations": [ { "location_id": "11111111-1111-4111-8111-000000001107", "archived": false } ], "tags": [ { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer" } ], "lead_sources": [ { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral" } ], "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "Page contacts", "description": "People and communication channels with complete account-specific primary and archive state. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example", "first_name": "Jordan", "last_name": "Example", "salutation": null, "title": null, "email_addresses": [ { "id": "11111111-1111-4111-8111-000000001111", "address": "jordan@example.invalid", "usage": "PRIMARY" } ], "phone_numbers": [ { "id": "11111111-1111-4111-8111-000000001112", "number": "+12025550123", "type": "MOBILE", "usage": "PRIMARY" } ], "accounts": [ { "id": "11111111-1111-4111-8111-000000001108", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "is_primary": true, "archived": false } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Read one contact", "description": "People and communication channels with complete account-specific primary and archive state.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example", "first_name": "Jordan", "last_name": "Example", "salutation": null, "title": null, "email_addresses": [ { "id": "11111111-1111-4111-8111-000000001111", "address": "jordan@example.invalid", "usage": "PRIMARY" } ], "phone_numbers": [ { "id": "11111111-1111-4111-8111-000000001112", "number": "+12025550123", "type": "MOBILE", "usage": "PRIMARY" } ], "accounts": [ { "id": "11111111-1111-4111-8111-000000001108", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "is_primary": true, "archived": false } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/locations": { "get": { "operationId": "listLocations", "tags": [ "Locations" ], "summary": "Page locations", "description": "Service places with addresses, property information, and complete account associations. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null }, "required": false, "name": "property_type", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001107", "name": "Home", "address": { "id": "11111111-1111-4111-8111-000000001104", "formatted": "123 Example Lane, Los Angeles, CA 90001", "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "property_type": "Single Family Home", "municipality": "Los Angeles", "estimated_square_footage": 1600, "estimated_build_date": null, "description": null, "accounts": [ { "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "archived": false } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/locations/{id}": { "get": { "operationId": "getLocation", "tags": [ "Locations" ], "summary": "Read one location", "description": "Service places with addresses, property information, and complete account associations.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001107", "name": "Home", "address": { "id": "11111111-1111-4111-8111-000000001104", "formatted": "123 Example Lane, Los Angeles, CA 90001", "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "property_type": "Single Family Home", "municipality": "Los Angeles", "estimated_square_footage": 1600, "estimated_build_date": null, "description": null, "accounts": [ { "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "archived": false } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/jobs": { "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "summary": "Page jobs", "description": "Work and opportunities with current lifecycle status, recorded dimensions, and distinct work-completion and lifecycle-closure dates. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "$ref": "#/components/schemas/NullableJobClass" }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "status_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "Opportunity", "Upcoming", "Ongoing", "Won", "Closed", null ] }, "required": false, "name": "stage", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "created_by_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "completed_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "completed_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "closed_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null }, "required": false, "name": "closed_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "summary": "Repair air conditioner", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "contact": { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example" }, "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "lifecycle": { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow" }, "status": { "id": "11111111-1111-4111-8111-000000001103", "name": "Ready to invoice", "description": "", "stage": "Won", "special_status": "Completed", "is_default": false, "is_work_complete": true, "is_lead_won": true }, "status_changed_at": "2026-08-20T15:00:00Z", "work_completed_at": "2026-08-20T15:00:00Z", "lifecycle_closed_at": null, "outcomes": { "is_opportunity": true, "is_converted": true, "is_hot_lead": false }, "tags": [ { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer" } ], "lead_sources": [ { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral" } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "Read one job", "description": "Work and opportunities with current lifecycle status, recorded dimensions, and distinct work-completion and lifecycle-closure dates.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "summary": "Repair air conditioner", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "contact": { "id": "11111111-1111-4111-8111-000000001101", "name": "Jordan Example" }, "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "lifecycle": { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow" }, "status": { "id": "11111111-1111-4111-8111-000000001103", "name": "Ready to invoice", "description": "", "stage": "Won", "special_status": "Completed", "is_default": false, "is_work_complete": true, "is_lead_won": true }, "status_changed_at": "2026-08-20T15:00:00Z", "work_completed_at": "2026-08-20T15:00:00Z", "lifecycle_closed_at": null, "outcomes": { "is_opportunity": true, "is_converted": true, "is_hot_lead": false }, "tags": [ { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer" } ], "lead_sources": [ { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral" } ], "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-appointments": { "get": { "operationId": "listJobAppointments", "tags": [ "JobAppointments" ], "summary": "Page job appointments", "description": "Customer visit windows with confirmation and cancellation state. One appointment is one visit, regardless of its technician count. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "created_by_id", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "confirmed", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "canceled", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null }, "required": false, "name": "starts_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null }, "required": false, "name": "starts_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAppointmentPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001109", "number": "300", "job_id": "11111111-1111-4111-8111-000000000501", "type": "Other", "description": "Air conditioner repair visit", "window_start_at": "2026-08-20T13:00:00Z", "window_end_at": "2026-08-20T15:00:00Z", "confirmed": true, "canceled": false, "cancellation_reason": null, "cancellation_note": null, "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-appointments/{id}": { "get": { "operationId": "getJobAppointment", "tags": [ "JobAppointments" ], "summary": "Read one job appointment", "description": "Customer visit windows with confirmation and cancellation state. One appointment is one visit, regardless of its technician count.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAppointmentResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001109", "number": "300", "job_id": "11111111-1111-4111-8111-000000000501", "type": "Other", "description": "Air conditioner repair visit", "window_start_at": "2026-08-20T13:00:00Z", "window_end_at": "2026-08-20T15:00:00Z", "confirmed": true, "canceled": false, "cancellation_reason": null, "cancellation_note": null, "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-assignments": { "get": { "operationId": "listJobAssignments", "tags": [ "JobAssignments" ], "summary": "Page job assignments", "description": "A member assignment to a visit, including its scheduled span and recorded execution status. This does not establish attendance or actual hours worked. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "appointment_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "team_member_id", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "TO_DO", "EN_ROUTE", "IN_PROGRESS", "COMPLETED", "CANCELED" ] }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null }, "required": false, "name": "starts_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null }, "required": false, "name": "starts_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAssignmentPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001113", "job_id": "11111111-1111-4111-8111-000000000501", "appointment_id": "11111111-1111-4111-8111-000000001109", "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "starts_at": "2026-08-20T13:30:00Z", "ends_at": "2026-08-20T14:30:00Z", "status": "COMPLETED", "status_updated_at": "2026-08-20T15:00:00Z", "created_at": "2026-08-19T16:00:00Z", "updated_at": null } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-assignments/{id}": { "get": { "operationId": "getJobAssignment", "tags": [ "JobAssignments" ], "summary": "Read one job assignment", "description": "A member assignment to a visit, including its scheduled span and recorded execution status. This does not establish attendance or actual hours worked.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAssignmentResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001113", "job_id": "11111111-1111-4111-8111-000000000501", "appointment_id": "11111111-1111-4111-8111-000000001109", "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "starts_at": "2026-08-20T13:30:00Z", "ends_at": "2026-08-20T14:30:00Z", "status": "COMPLETED", "status_updated_at": "2026-08-20T15:00:00Z", "created_at": "2026-08-19T16:00:00Z", "updated_at": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/business-units": { "get": { "operationId": "listBusinessUnits", "tags": [ "BusinessUnits" ], "summary": "Page business units", "description": "Company business units for joining and segmenting operational records. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessUnitPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000201", "name": "Service", "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/business-units/{id}": { "get": { "operationId": "getBusinessUnit", "tags": [ "BusinessUnits" ], "summary": "Read one business unit", "description": "Company business units for joining and segmenting operational records.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessUnitResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service", "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-types": { "get": { "operationId": "listJobTypes", "tags": [ "JobTypes" ], "summary": "Page job types", "description": "Configured job types, including archived types, with their class, lifecycle, and default business unit. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "archived", "in": "query" }, { "schema": { "$ref": "#/components/schemas/NullableJobClass" }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "lifecycle_id", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTypePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service", "description": "Residential HVAC service", "lifecycle": { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow" }, "job_class": "SERVICE", "default_business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "duration_minutes": 60, "is_opportunity": true, "archived_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-types/{id}": { "get": { "operationId": "getJobType", "tags": [ "JobTypes" ], "summary": "Read one job type", "description": "Configured job types, including archived types, with their class, lifecycle, and default business unit.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTypeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service", "description": "Residential HVAC service", "lifecycle": { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow" }, "job_class": "SERVICE", "default_business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "duration_minutes": 60, "is_opportunity": true, "archived_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-classes": { "get": { "operationId": "listJobClasses", "tags": [ "JobClasses" ], "summary": "Page job classes", "description": "Existing job-class codes and display names, including legacy classes. IDs are class codes. Orders by id ascending; no timestamps or update filter. ", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/JobClass" }, "minItems": 1, "maxItems": 100, "default": null }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobClassPage" }, "example": { "data": [ { "id": "SERVICE", "name": "Service" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-classes/{id}": { "get": { "operationId": "getJobClass", "tags": [ "JobClasses" ], "summary": "Read one job class", "description": "Existing job-class codes and display names, including legacy classes. IDs are class codes. Orders by id ascending; no timestamps or update filter.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/JobClass" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobClassResponse" }, "example": { "data": { "id": "SERVICE", "name": "Service" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-lifecycles": { "get": { "operationId": "listJobLifecycles", "tags": [ "JobLifecycles" ], "summary": "Page job lifecycles", "description": "Configured lifecycles, including archived lifecycles, with complete ordered statuses and their stage and special-status meaning. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLifecyclePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow", "description": "Service jobs from opportunity to closure", "type": "JOB", "archived": false, "statuses": [ { "id": "11111111-1111-4111-8111-000000001103", "name": "Ready to invoice", "description": "", "stage": "Won", "special_status": "Completed", "is_default": false, "is_work_complete": true, "is_lead_won": true } ], "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-lifecycles/{id}": { "get": { "operationId": "getJobLifecycle", "tags": [ "JobLifecycles" ], "summary": "Read one job lifecycle", "description": "Configured lifecycles, including archived lifecycles, with complete ordered statuses and their stage and special-status meaning.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLifecycleResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001102", "name": "Service workflow", "description": "Service jobs from opportunity to closure", "type": "JOB", "archived": false, "statuses": [ { "id": "11111111-1111-4111-8111-000000001103", "name": "Ready to invoice", "description": "", "stage": "Won", "special_status": "Completed", "is_default": false, "is_work_complete": true, "is_lead_won": true } ], "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/lead-sources": { "get": { "operationId": "listLeadSources", "tags": [ "LeadSources" ], "summary": "Page lead sources", "description": "Configured company source names and canonical identity, including archived sources. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSourcePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral", "canonical_name": "Referral", "archived_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/lead-sources/{id}": { "get": { "operationId": "getLeadSource", "tags": [ "LeadSources" ], "summary": "Read one lead source", "description": "Configured company source names and canonical identity, including archived sources.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSourceResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001105", "name": "Referral", "canonical_name": "Referral", "archived_at": null, "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/tags": { "get": { "operationId": "listTags", "tags": [ "Tags" ], "summary": "Page tags", "description": "Company tags used to label customers and jobs. Orders by created_at then id ascending. Complete embedded relationships are returned on every page.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer", "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/tags/{id}": { "get": { "operationId": "getTag", "tags": [ "Tags" ], "summary": "Read one tag", "description": "Company tags used to label customers and jobs.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001106", "name": "Priority customer", "created_at": "2026-08-19T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/estimates": { "get": { "operationId": "listEstimates", "tags": [ "Estimates" ], "summary": "Page estimates", "description": "Proposals with complete options, lines, discounts, recorded totals, selection, current acceptance/loss information, and all resulting invoice IDs. Alternatives are not additive estimate value. Orders by created_at then id ascending. All statuses and complete embedded children are included by default.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "Original proposal job only." }, "required": false, "description": "Original proposal job only.", "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "created_by_id", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/EstimateStatus" }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Inclusive company-local recorded acceptance date, regardless of current status." }, "required": false, "description": "Inclusive company-local recorded acceptance date, regardless of current status.", "name": "accepted_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Exclusive company-local recorded acceptance date, regardless of current status." }, "required": false, "description": "Exclusive company-local recorded acceptance date, regardless of current status.", "name": "accepted_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimatePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001201", "number": "400", "status": "ACCEPTED", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "job_id": "11111111-1111-4111-8111-000000000501", "location_id": "11111111-1111-4111-8111-000000001107", "job_appointment_id": "11111111-1111-4111-8111-000000001109", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T17:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "accepted_at": "2026-08-20T14:00:00Z", "accepted_on_behalf_by": null, "last_sent_at": "2026-08-19T18:00:00Z", "message": "Repair and replacement alternatives.", "closed_lost_reason": { "category": null, "note": null }, "currency": "USD", "pricing_multiplier": 1, "tax": { "name": "Sales tax", "rate": 0.1 }, "accepted_total_cents": 99000, "invoice_ids": [ "11111111-1111-4111-8111-000000000601" ], "options": [ { "id": "11111111-1111-4111-8111-000000001202", "position": 0, "name": "Repair", "description": "Restore the existing system.", "selected": true, "recommended": false, "total_cents": 99000, "tax_rounding": "round", "line_items": [ { "id": "11111111-1111-4111-8111-000000001203", "position": 0, "name": "HVAC repair", "description": "Repair existing equipment", "item_type": "SERVICE", "code": "REPAIR", "variant": null, "pricebook_item_id": null, "quantity": 1, "unit_price_cents": 100000, "taxable": true, "discountable": true } ], "discounts": [ { "id": "11111111-1111-4111-8111-000000001204", "position": 0, "name": "Service discount", "description": null, "type": "FLAT", "amount_cents": 10000, "rate": null } ] }, { "id": "11111111-1111-4111-8111-000000001205", "position": 1, "name": "Replace", "description": "Replace the system.", "selected": false, "recommended": true, "total_cents": 880000, "tax_rounding": "round", "line_items": [ { "id": "11111111-1111-4111-8111-000000001206", "position": 0, "name": "Replacement system", "description": null, "item_type": "EQUIPMENT", "code": null, "variant": null, "pricebook_item_id": null, "quantity": 1, "unit_price_cents": 800000, "taxable": true, "discountable": true } ], "discounts": [] } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/estimates/{id}": { "get": { "operationId": "getEstimate", "tags": [ "Estimates" ], "summary": "Read one estimate", "description": "Proposals with complete options, lines, discounts, recorded totals, selection, current acceptance/loss information, and all resulting invoice IDs. Alternatives are not additive estimate value.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001201", "number": "400", "status": "ACCEPTED", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "job_id": "11111111-1111-4111-8111-000000000501", "location_id": "11111111-1111-4111-8111-000000001107", "job_appointment_id": "11111111-1111-4111-8111-000000001109", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-19T17:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "accepted_at": "2026-08-20T14:00:00Z", "accepted_on_behalf_by": null, "last_sent_at": "2026-08-19T18:00:00Z", "message": "Repair and replacement alternatives.", "closed_lost_reason": { "category": null, "note": null }, "currency": "USD", "pricing_multiplier": 1, "tax": { "name": "Sales tax", "rate": 0.1 }, "accepted_total_cents": 99000, "invoice_ids": [ "11111111-1111-4111-8111-000000000601" ], "options": [ { "id": "11111111-1111-4111-8111-000000001202", "position": 0, "name": "Repair", "description": "Restore the existing system.", "selected": true, "recommended": false, "total_cents": 99000, "tax_rounding": "round", "line_items": [ { "id": "11111111-1111-4111-8111-000000001203", "position": 0, "name": "HVAC repair", "description": "Repair existing equipment", "item_type": "SERVICE", "code": "REPAIR", "variant": null, "pricebook_item_id": null, "quantity": 1, "unit_price_cents": 100000, "taxable": true, "discountable": true } ], "discounts": [ { "id": "11111111-1111-4111-8111-000000001204", "position": 0, "name": "Service discount", "description": null, "type": "FLAT", "amount_cents": 10000, "rate": null } ] }, { "id": "11111111-1111-4111-8111-000000001205", "position": 1, "name": "Replace", "description": "Replace the system.", "selected": false, "recommended": true, "total_cents": 880000, "tax_rounding": "round", "line_items": [ { "id": "11111111-1111-4111-8111-000000001206", "position": 0, "name": "Replacement system", "description": null, "item_type": "EQUIPMENT", "code": null, "variant": null, "pricebook_item_id": null, "quantity": 1, "unit_price_cents": 800000, "taxable": true, "discountable": true } ], "discounts": [] } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-leads": { "get": { "operationId": "listJobLeads", "tags": [ "JobLeads" ], "summary": "Page job leads", "description": "Submitted service requests with captured contact/address, free-form intake source, and recorded conversion state. A converted lead is not evidence of a sale; multiple leads can refer to one job. Orders by created_at then id ascending. All statuses and complete embedded children are included by default.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/JobLeadStatus" }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "existing_location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "submitted_job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null }, "required": false, "name": "request_type", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Exact, case-sensitive match of recorded intake text." }, "required": false, "description": "Exact, case-sensitive match of recorded intake text.", "name": "source_text", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLeadPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000001207", "status": "converted", "created_at": "2026-08-18T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "summary": "Air conditioner stopped cooling.", "request_type": "SERVICE", "submitted_account_type": "Residential", "submitted_service_type": null, "submitted_job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "source_text": "Booking Website", "contact": { "first_name": "Jordan", "last_name": "Example", "email_address": "jordan@example.invalid", "phone_number": "+12025550123" }, "service_address": { "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "existing_location_id": null, "job_id": "11111111-1111-4111-8111-000000000501" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-leads/{id}": { "get": { "operationId": "getJobLead", "tags": [ "JobLeads" ], "summary": "Read one job lead", "description": "Submitted service requests with captured contact/address, free-form intake source, and recorded conversion state. A converted lead is not evidence of a sale; multiple leads can refer to one job.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLeadResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000001207", "status": "converted", "created_at": "2026-08-18T16:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "summary": "Air conditioner stopped cooling.", "request_type": "SERVICE", "submitted_account_type": "Residential", "submitted_service_type": null, "submitted_job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "source_text": "Booking Website", "contact": { "first_name": "Jordan", "last_name": "Example", "email_address": "jordan@example.invalid", "phone_number": "+12025550123" }, "service_address": { "line_1": "123 Example Lane", "line_2": null, "city": "Los Angeles", "state": "CA", "postal_code": "90001" }, "existing_location_id": null, "job_id": "11111111-1111-4111-8111-000000000501" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/equipment": { "get": { "operationId": "listEquipment", "tags": [ "Equipment" ], "summary": "Page equipment", "description": "Installed items at owned locations, with recorded condition, lifecycle dates, warranty terms, and optional same-location HVAC grouping. All operational statuses are included by default. No inferred age, warranty eligibility, or item service history. Orders by id ascending. List and detail return the same complete representation. updated_since covers parent-row saves only.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "Any owned account association at the equipment location, including archived associations." }, "required": false, "description": "Any owned account association at the equipment location, including archived associations.", "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "hvac_system_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null }, "required": false, "name": "equipment_type", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "minItems": 1, "default": null }, "required": false, "style": "form", "explode": true, "name": "status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null }, "required": false, "name": "condition", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null }, "required": false, "name": "manufacturer", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000004101", "location_id": "11111111-1111-4111-8111-000000001107", "hvac_system": { "id": "11111111-1111-4111-8111-000000004102", "name": "Downstairs" }, "equipment_type": "AIR_CONDITIONER", "status": "IN_SERVICE", "condition": "FAIR", "manufacturer": "Example Equipment", "model_number": "AC-36", "serial_number": "EXAMPLE-001", "description": "Outdoor condenser", "dimensions": "36 × 36 × 40 inches", "manufacturing_date": "2014-01-01", "installation": { "date": "2014-06-15", "party": "EXTERNAL" }, "estimated_end_of_life_date": "2029-06-15", "average_life_expectancy_years": 15, "manufacturer_warranty": { "start_date": "2014-06-15", "end_date": "2024-06-15", "terms": "Recorded ten-year limited parts warranty" }, "labor_warranty": { "start_date": null, "end_date": null, "terms": null }, "created_at": null, "updated_at": "2026-09-08T19:00:00Z" } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/equipment/{id}": { "get": { "operationId": "getEquipment", "tags": [ "Equipment" ], "summary": "Read one equipment", "description": "Installed items at owned locations, with recorded condition, lifecycle dates, warranty terms, and optional same-location HVAC grouping. All operational statuses are included by default. No inferred age, warranty eligibility, or item service history.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000004101", "location_id": "11111111-1111-4111-8111-000000001107", "hvac_system": { "id": "11111111-1111-4111-8111-000000004102", "name": "Downstairs" }, "equipment_type": "AIR_CONDITIONER", "status": "IN_SERVICE", "condition": "FAIR", "manufacturer": "Example Equipment", "model_number": "AC-36", "serial_number": "EXAMPLE-001", "description": "Outdoor condenser", "dimensions": "36 × 36 × 40 inches", "manufacturing_date": "2014-01-01", "installation": { "date": "2014-06-15", "party": "EXTERNAL" }, "estimated_end_of_life_date": "2029-06-15", "average_life_expectancy_years": 15, "manufacturer_warranty": { "start_date": "2014-06-15", "end_date": "2024-06-15", "terms": "Recorded ten-year limited parts warranty" }, "labor_warranty": { "start_date": null, "end_date": null, "terms": null }, "created_at": null, "updated_at": "2026-09-08T19:00:00Z" }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/form-responses": { "get": { "operationId": "listFormResponses", "tags": [ "FormResponses" ], "summary": "Page form responses", "description": "Captured visit forms with complete questions, recorded answers, original work relationships, and current required-data completeness. Current templates do not replace captured content. Unsupported capture returns null questions and completeness while retaining safe metadata. Orders by id ascending. List and detail return the same complete representation. updated_since covers parent-row saves only.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive parent-record updated_at filter only; not a complete change feed." }, "required": false, "description": "Inclusive parent-record updated_at filter only; not a complete change feed.", "name": "updated_since", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "appointment_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "Original captured appointment’s job; follow-up reuse does not duplicate responses." }, "required": false, "description": "Original captured appointment’s job; follow-up reuse does not duplicate responses.", "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "form_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "last_edited_by_id", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "ad_hoc", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponsePage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000004103", "form_id": "11111111-1111-4111-8111-000000004104", "name": "Air conditioning inspection", "instance_number": 2, "label": "Downstairs condenser", "ad_hoc": true, "appointment_id": "11111111-1111-4111-8111-000000001109", "job_id": "11111111-1111-4111-8111-000000000501", "account_id": "11111111-1111-4111-8111-000000000101", "location_id": "11111111-1111-4111-8111-000000001107", "last_edited_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-20T14:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "completed": false, "questions": [ { "question_id": "11111111-1111-4111-8111-000000004105", "answer_path": "/items/1/response", "section": "Outdoor equipment", "label": "Equipment operates normally?", "type": "YES_NO", "required": true, "helper_text": null, "value": "No", "photo_requirement": "NONE", "attached_photo_url": null }, { "question_id": null, "answer_path": "/items/2/left/0/response", "section": "Outdoor equipment", "label": "Condition", "type": "PASS_FAIL_FLAG", "required": true, "helper_text": null, "value": "Flag", "photo_requirement": "OPTIONAL", "attached_photo_url": "https://example.invalid/inspection-photo.png" }, { "question_id": null, "answer_path": "/items/2/right/0/response", "section": "Outdoor equipment", "label": "Notes", "type": "TEXT", "required": true, "helper_text": "Explain the finding", "value": null, "photo_requirement": "NONE", "attached_photo_url": null } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/form-responses/{id}": { "get": { "operationId": "getFormResponse", "tags": [ "FormResponses" ], "summary": "Read one form response", "description": "Captured visit forms with complete questions, recorded answers, original work relationships, and current required-data completeness. Current templates do not replace captured content. Unsupported capture returns null questions and completeness while retaining safe metadata.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000004103", "form_id": "11111111-1111-4111-8111-000000004104", "name": "Air conditioning inspection", "instance_number": 2, "label": "Downstairs condenser", "ad_hoc": true, "appointment_id": "11111111-1111-4111-8111-000000001109", "job_id": "11111111-1111-4111-8111-000000000501", "account_id": "11111111-1111-4111-8111-000000000101", "location_id": "11111111-1111-4111-8111-000000001107", "last_edited_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "created_at": "2026-08-20T14:00:00Z", "updated_at": "2026-09-08T19:00:00Z", "completed": false, "questions": [ { "question_id": "11111111-1111-4111-8111-000000004105", "answer_path": "/items/1/response", "section": "Outdoor equipment", "label": "Equipment operates normally?", "type": "YES_NO", "required": true, "helper_text": null, "value": "No", "photo_requirement": "NONE", "attached_photo_url": null }, { "question_id": null, "answer_path": "/items/2/left/0/response", "section": "Outdoor equipment", "label": "Condition", "type": "PASS_FAIL_FLAG", "required": true, "helper_text": null, "value": "Flag", "photo_requirement": "OPTIONAL", "attached_photo_url": "https://example.invalid/inspection-photo.png" }, { "question_id": null, "answer_path": "/items/2/right/0/response", "section": "Outdoor equipment", "label": "Notes", "type": "TEXT", "required": true, "helper_text": "Explain the finding", "value": null, "photo_requirement": "NONE", "attached_photo_url": null } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/time-entries": { "get": { "operationId": "listTimeEntries", "tags": [ "TimeEntries" ], "summary": "Page recorded time entries", "description": "Effective corrected intervals, including custom activities and validated work links. Orders by created_at then id ascending. Soft-deleted entries require include_deleted=true. No reliable updated_since filter; refresh known IDs and effective-start windows. Elapsed duration is distinct from capped timesheet minutes.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "appointment_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "assignment_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive effective start instant." }, "required": false, "description": "Inclusive effective start instant.", "name": "starts_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive effective start instant; this is not an overlap filter." }, "required": false, "description": "Exclusive effective start instant; this is not an overlap filter.", "name": "starts_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Exact, case-sensitive recorded activity name." }, "required": false, "description": "Exact, case-sensitive recorded activity name.", "name": "activity_name", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null }, "required": false, "name": "payable", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": null, "description": "True selects entries with no effective end; false selects closed entries." }, "required": false, "description": "True selects entries with no effective end; false selects closed entries.", "name": "open", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include retained soft-deleted entries; hard-deleted records are unavailable." }, "required": false, "description": "Include retained soft-deleted entries; hard-deleted records are unavailable.", "name": "include_deleted", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeEntryPage" }, "example": { "data": [ { "id": "b1000000-0000-4000-8000-000000000001", "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "starts_at": "2026-09-08T19:30:00Z", "ends_at": "2026-09-08T20:30:30Z", "start_corrected": false, "end_corrected": true, "duration_minutes": 60.5, "activity": { "name": "ON-SITE", "kind": "ON-SITE" }, "payable": true, "job_id": "11111111-1111-4111-8111-000000000501", "appointment_id": "11111111-1111-4111-8111-000000001109", "assignment_id": "11111111-1111-4111-8111-000000001113", "attention_note": null, "deleted_at": null, "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "updated_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "deleted_by": null, "created_at": "2026-09-08T19:30:00Z", "updated_at": null } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/time-entries/{id}": { "get": { "operationId": "getTimeEntry", "tags": [ "TimeEntries" ], "summary": "Read one time entry", "description": "The same representation as collection pages. Retained soft-deleted entries require include_deleted=true.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "boolean", "default": false, "description": "Include retained soft-deleted entries; hard-deleted records are unavailable." }, "required": false, "description": "Include retained soft-deleted entries; hard-deleted records are unavailable.", "name": "include_deleted", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeEntryResponse" }, "example": { "data": { "id": "b1000000-0000-4000-8000-000000000001", "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "starts_at": "2026-09-08T19:30:00Z", "ends_at": "2026-09-08T20:30:30Z", "start_corrected": false, "end_corrected": true, "duration_minutes": 60.5, "activity": { "name": "ON-SITE", "kind": "ON-SITE" }, "payable": true, "job_id": "11111111-1111-4111-8111-000000000501", "appointment_id": "11111111-1111-4111-8111-000000001109", "assignment_id": "11111111-1111-4111-8111-000000001113", "attention_note": null, "deleted_at": null, "created_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "updated_by": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "deleted_by": null, "created_at": "2026-09-08T19:30:00Z", "updated_at": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/timesheets": { "get": { "operationId": "listTimesheets", "tags": [ "Timesheets" ], "summary": "Page members in a configured timesheet period", "description": "Required period_date selects a current configured company-local period. All current company members, including inactive and zero-entry members, ordered by member ID. Effective-start-in-period entries contribute; open, deleted, nonpayable and unknown-activity entries do not contribute payable minutes. Existing server timesheet rules use wall-clock minutes, cap days at 1439, and stop overnight spans at the end of their starting day. No payroll or costing calculation. Current configuration applies to historical dates. Cursor scope includes resolved boundaries.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Required company-local date within the desired configured period. Uses current company settings, even when time tracking is disabled. Returns 400 if no usable period configuration exists." }, "required": true, "description": "Required company-local date within the desired configured period. Uses current company settings, even when time tracking is disabled. Returns 400 if no usable period configuration exists.", "name": "period_date", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "team_member_id", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetPage" }, "example": { "data": [ { "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "period": { "start_date": "2026-09-07", "end_date_exclusive": "2026-09-14" }, "entry_count": 1, "open_entry_count": 0, "unknown_activity_entry_count": 0, "payable_minutes": 60, "days": [ { "date": "2026-09-07", "payable_minutes": 0 }, { "date": "2026-09-08", "payable_minutes": 60 }, { "date": "2026-09-09", "payable_minutes": 0 }, { "date": "2026-09-10", "payable_minutes": 0 }, { "date": "2026-09-11", "payable_minutes": 0 }, { "date": "2026-09-12", "payable_minutes": 0 }, { "date": "2026-09-13", "payable_minutes": 0 } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/timesheets/{team_member_id}": { "get": { "operationId": "getTimesheet", "tags": [ "Timesheets" ], "summary": "Read one member’s configured-period timesheet", "description": "Derived representation identified by team member and resolved period dates. Required period_date is a local calendar date. Includes a zero total when the member has no entries. Returns 400 for missing or unusable configuration and 404 for a missing or foreign member.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "team_member_id", "in": "path" }, { "schema": { "type": "string", "format": "date", "description": "Required company-local date within the desired configured period. Uses current company settings, even when time tracking is disabled. Returns 400 if no usable period configuration exists." }, "required": true, "description": "Required company-local date within the desired configured period. Uses current company settings, even when time tracking is disabled. Returns 400 if no usable period configuration exists.", "name": "period_date", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetResponse" }, "example": { "data": { "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "period": { "start_date": "2026-09-07", "end_date_exclusive": "2026-09-14" }, "entry_count": 1, "open_entry_count": 0, "unknown_activity_entry_count": 0, "payable_minutes": 60, "days": [ { "date": "2026-09-07", "payable_minutes": 0 }, { "date": "2026-09-08", "payable_minutes": 60 }, { "date": "2026-09-09", "payable_minutes": 0 }, { "date": "2026-09-10", "payable_minutes": 0 }, { "date": "2026-09-11", "payable_minutes": 0 }, { "date": "2026-09-12", "payable_minutes": 0 }, { "date": "2026-09-13", "payable_minutes": 0 } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-financials": { "get": { "operationId": "listJobFinancials", "tags": [ "JobFinancials" ], "summary": "Page jobs with recorded costs and costing revenue", "description": "One resource per owned job, identified by job ID and ordered by ID ascending. Complete saved costs, qualifying invoice facts and distinct assigned company members. Disabled or untracked costing has null totals while saved facts remain readable. Date filters refer to job creation or the company-local financial report date. No financial updated_since or snapshot.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report." }, "required": false, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report.", "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Inclusive company-local job financial report date." }, "required": false, "description": "Inclusive company-local job financial report date.", "name": "report_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Exclusive company-local job financial report date." }, "required": false, "description": "Exclusive company-local job financial report date.", "name": "report_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "NOT_TRACKED", "TRACKED", null ] }, "required": false, "name": "tracking_status", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "UNVERIFIED", "VERIFIED", null ] }, "required": false, "name": "verification_status", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFinancialsPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "participants": [ { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" } ], "created_at": "2026-08-19T16:00:00Z", "report_date": "2026-08-20", "report_date_basis": "INVOICE_ISSUED", "costing": { "enabled": true, "tracking_status": "TRACKED", "verification_status": "VERIFIED", "job_type_included": true }, "currency": "USD", "totals": { "revenue_cents": 130000, "labor_cost_cents": 6000, "parts_cost_cents": 24000, "equipment_cost_cents": 0, "misc_cost_cents": 0, "other_cost_cents": 0, "total_cost_cents": 30000, "gross_profit_cents": 100000, "gross_margin": 0.7692 }, "invoices": [ { "id": "11111111-1111-4111-8111-000000000601", "number": "1001", "status": "OPEN", "issued_at": "2026-08-20T16:00:00Z", "subtotal_cents": 100000 }, { "id": "11111111-1111-4111-8111-000000000602", "number": "1002", "status": "PAID", "issued_at": "2026-09-02T16:00:00Z", "subtotal_cents": 30000 } ], "cost_entries": [ { "id": "11111111-1111-4111-8111-000000001501", "category": "labor", "source": "manual", "name": "Recorded service labor", "quantity": 120, "quantity_unit": "minute", "unit_cost_cents": 3000, "total_cents": 6000, "labor_activity": "On Site", "misc_category": null, "pricebook_item_id": null, "created_at": "2026-09-08T19:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, { "id": "11111111-1111-4111-8111-000000001502", "category": "parts", "source": "invoice", "name": "Recorded replacement part", "quantity": 2, "quantity_unit": "unit", "unit_cost_cents": 12000, "total_cents": 24000, "labor_activity": null, "misc_category": null, "pricebook_item_id": null, "created_at": "2026-09-08T19:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/job-financials/{id}": { "get": { "operationId": "getJobFinancials", "tags": [ "JobFinancials" ], "summary": "Read the recorded financials of one job", "description": "The same complete representation as collection pages, using the job ID. Reads saved costs without populating or synchronizing them from timekeeping, wages, invoices or pricebook data.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFinancialsResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "participants": [ { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" } ], "created_at": "2026-08-19T16:00:00Z", "report_date": "2026-08-20", "report_date_basis": "INVOICE_ISSUED", "costing": { "enabled": true, "tracking_status": "TRACKED", "verification_status": "VERIFIED", "job_type_included": true }, "currency": "USD", "totals": { "revenue_cents": 130000, "labor_cost_cents": 6000, "parts_cost_cents": 24000, "equipment_cost_cents": 0, "misc_cost_cents": 0, "other_cost_cents": 0, "total_cost_cents": 30000, "gross_profit_cents": 100000, "gross_margin": 0.7692 }, "invoices": [ { "id": "11111111-1111-4111-8111-000000000601", "number": "1001", "status": "OPEN", "issued_at": "2026-08-20T16:00:00Z", "subtotal_cents": 100000 }, { "id": "11111111-1111-4111-8111-000000000602", "number": "1002", "status": "PAID", "issued_at": "2026-09-02T16:00:00Z", "subtotal_cents": 30000 } ], "cost_entries": [ { "id": "11111111-1111-4111-8111-000000001501", "category": "labor", "source": "manual", "name": "Recorded service labor", "quantity": 120, "quantity_unit": "minute", "unit_cost_cents": 3000, "total_cents": 6000, "labor_activity": "On Site", "misc_category": null, "pricebook_item_id": null, "created_at": "2026-09-08T19:00:00Z", "updated_at": "2026-09-08T19:00:00Z" }, { "id": "11111111-1111-4111-8111-000000001502", "category": "parts", "source": "invoice", "name": "Recorded replacement part", "quantity": 2, "quantity_unit": "unit", "unit_cost_cents": 12000, "total_cents": 24000, "labor_activity": null, "misc_category": null, "pricebook_item_id": null, "created_at": "2026-09-08T19:00:00Z", "updated_at": "2026-09-08T19:00:00Z" } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/job-profitability": { "get": { "operationId": "getJobProfitability", "tags": [ "Reports" ], "summary": "Summarize recorded job profitability", "description": "Enabled costing and TRACKED jobs only; defaults to VERIFIED jobs and included owned job types. Revenue is recorded OPEN/PAID/UNCOLLECTABLE pre-discount, pre-tax invoice subtotals. Whole-job date is earliest qualifying invoice issue time, then work completion, then job creation, in company timezone. One optional business grouping plus time; null business groups retained when eligible. Rows order by period_start then group value, null first. Empty buckets omitted. Margin is calculated from summed amounts, not averaged job margins.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "required": true, "description": "Inclusive company-local date.", "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "required": true, "description": "Exclusive company-local date; must be after start_date.", "name": "end_date", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "required": false, "name": "bucket", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "business_unit", "job_type", "job_class", null ] }, "required": false, "name": "group_by", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report." }, "required": false, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report.", "name": "team_member_id", "in": "query" }, { "schema": { "type": "boolean", "default": true }, "required": false, "name": "verified_only", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include excluded or unavailable job-type mappings. Disabled costing and untracked jobs remain excluded." }, "required": false, "description": "Include excluded or unavailable job-type mappings. Disabled costing and untracked jobs remain excluded.", "name": "include_excluded_job_types", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobProfitabilityResponse" }, "example": { "data": [ { "period_start": "2026-08-01", "period_end": "2026-09-01", "currency": "USD", "group": null, "job_count": 1, "revenue_cents": 130000, "labor_cost_cents": 6000, "parts_cost_cents": 24000, "equipment_cost_cents": 0, "misc_cost_cents": 0, "other_cost_cents": 0, "total_cost_cents": 30000, "gross_profit_cents": 100000, "gross_margin": 0.7692 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "start_date": "2026-08-01", "end_date": "2026-10-01", "bucket": "month", "costing_enabled": true, "verified_only": true, "include_excluded_job_types": false, "group_by": null } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/technician-participation-profitability": { "get": { "operationId": "getTechnicianParticipationProfitability", "tags": [ "Reports" ], "summary": "Summarize full-job profitability for assigned members", "description": "Same date, revenue, cost and eligibility basis as job profitability. Each distinct validated assigned company member receives the entire job result once across repeated appointments. Inactive members and canceled visits remain included; assignment does not prove attendance. Unassigned jobs have no member row. Member rows overlap and must not be summed as company totals. Rows order by period_start then member ID. This is participation, not sold/earned attribution or an allocation of profit.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "required": true, "description": "Inclusive company-local date.", "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "required": true, "description": "Exclusive company-local date; must be after start_date.", "name": "end_date", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "required": false, "name": "bucket", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report." }, "required": false, "description": "A validated assigned member. Selects distinct jobs for job financials/profitability and only that member for the participation report.", "name": "team_member_id", "in": "query" }, { "schema": { "type": "boolean", "default": true }, "required": false, "name": "verified_only", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include excluded or unavailable job-type mappings. Disabled costing and untracked jobs remain excluded." }, "required": false, "description": "Include excluded or unavailable job-type mappings. Disabled costing and untracked jobs remain excluded.", "name": "include_excluded_job_types", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TechnicianParticipationResponse" }, "example": { "data": [ { "period_start": "2026-08-01", "period_end": "2026-09-01", "currency": "USD", "group": { "dimension": "team_member", "value": "11111111-1111-4111-8111-000000000401", "label": "Alex Example" }, "job_count": 1, "revenue_cents": 130000, "labor_cost_cents": 6000, "parts_cost_cents": 24000, "equipment_cost_cents": 0, "misc_cost_cents": 0, "other_cost_cents": 0, "total_cost_cents": 30000, "gross_profit_cents": 100000, "gross_margin": 0.7692 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "start_date": "2026-08-01", "end_date": "2026-10-01", "bucket": "month", "costing_enabled": true, "verified_only": true, "include_excluded_job_types": false, "group_by": "team_member" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/revenue-attributions": { "get": { "operationId": "listRevenueAttributions", "tags": [ "RevenueAttributions" ], "summary": "Page jobs with complete saved sold and earned credits", "description": "One resource per owned job, including empty credit arrays and undated jobs. Orders by job ID ascending. Member and credit-type filters must match the same credit to select a job; the returned array stays complete. Amounts preserve explicit recorded credits, including zero and negative values. No inferred attribution, save timestamp or updated_since.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "default": null, "description": "Repeat ids for a bounded ID set. Valid foreign or missing IDs contribute no list rows." }, "required": false, "style": "form", "explode": true, "name": "ids", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Inclusive creation instant." }, "required": false, "description": "Inclusive creation instant.", "name": "created_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "default": null, "description": "Exclusive creation instant." }, "required": false, "description": "Exclusive creation instant.", "name": "created_before", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "A currently validated credited company member." }, "required": false, "description": "A currently validated credited company member.", "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SOLD", "EARNED", null ] }, "required": false, "name": "credit_type", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "location_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Inclusive company-local work-completion date." }, "required": false, "description": "Inclusive company-local work-completion date.", "name": "report_from", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date", "default": null, "description": "Exclusive company-local work-completion date." }, "required": false, "description": "Exclusive company-local work-completion date.", "name": "report_before", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueAttributionsPage" }, "example": { "data": [ { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_at": "2026-08-19T16:00:00Z", "work_completed_at": "2026-08-20T15:00:00Z", "report_date": "2026-08-20", "currency": "USD", "credits": [ { "credit_type": "SOLD", "revenue_cents": 100000, "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice": { "id": "11111111-1111-4111-8111-000000000601", "number": "1001" }, "invoice_line_item_ids": [ "11111111-1111-4111-8111-000000000901" ] }, { "credit_type": "EARNED", "revenue_cents": 100000, "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice": { "id": "11111111-1111-4111-8111-000000000601", "number": "1001" }, "invoice_line_item_ids": [ "11111111-1111-4111-8111-000000000901" ] }, { "credit_type": "SOLD", "revenue_cents": 0, "team_member": null, "invoice": null, "invoice_line_item_ids": [] } ] } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/revenue-attributions/{id}": { "get": { "operationId": "getRevenueAttributions", "tags": [ "RevenueAttributions" ], "summary": "Read the complete saved revenue credits of one job", "description": "Uses the job ID and returns the same complete representation as collection pages. Replace the entire credit array when refreshing. Unavailable current references remain null or empty while owned credit amounts remain readable. Matching invoice lines provide context only; several may match one saved credit.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueAttributionsResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-000000000501", "number": "200", "account": { "id": "11111111-1111-4111-8111-000000000101", "name": "Example Household" }, "location_id": "11111111-1111-4111-8111-000000001107", "business_unit": { "id": "11111111-1111-4111-8111-000000000201", "name": "Service" }, "job_type": { "id": "11111111-1111-4111-8111-000000000301", "name": "HVAC Service" }, "job_class": "SERVICE", "created_at": "2026-08-19T16:00:00Z", "work_completed_at": "2026-08-20T15:00:00Z", "report_date": "2026-08-20", "currency": "USD", "credits": [ { "credit_type": "SOLD", "revenue_cents": 100000, "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice": { "id": "11111111-1111-4111-8111-000000000601", "number": "1001" }, "invoice_line_item_ids": [ "11111111-1111-4111-8111-000000000901" ] }, { "credit_type": "EARNED", "revenue_cents": 100000, "team_member": { "id": "11111111-1111-4111-8111-000000000401", "name": "Alex Example" }, "invoice": { "id": "11111111-1111-4111-8111-000000000601", "number": "1001" }, "invoice_line_item_ids": [ "11111111-1111-4111-8111-000000000901" ] }, { "credit_type": "SOLD", "revenue_cents": 0, "team_member": null, "invoice": null, "invoice_line_item_ids": [] } ] }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } }, "/reports/revenue-attribution": { "get": { "operationId": "getRevenueAttribution", "tags": [ "Reports" ], "summary": "Summarize recorded sold and earned credits by member", "description": "Company-local work-completion date with no fallback. Fixed credited-member grouping; unavailable members share a null group. Separate saved sold/earned cents and credit counts, plus distinct contributing job count. Filters select credits. No invoice-payment, assignment or costing eligibility requirement. Member credits overlap; sold and earned are separate measures, not additive company revenue. Rows order by period_start then member ID, null first; empty buckets omitted and periods clipped to the request.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum parent records or report rows. Complete children are always included." }, "required": false, "description": "Maximum parent records or report rows. Complete children are always included.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "nullable": true, "minLength": 1, "default": null, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR." }, "required": false, "description": "Repeat the original filters; any valid page size may continue. Foreign-company, tampered or mismatched cursors return INVALID_CURSOR.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Inclusive company-local date." }, "required": true, "description": "Inclusive company-local date.", "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Exclusive company-local date; must be after start_date." }, "required": true, "description": "Exclusive company-local date; must be after start_date.", "name": "end_date", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ], "default": "month" }, "required": false, "name": "bucket", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "account_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "business_unit_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null }, "required": false, "name": "job_type_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SERVICE", "MAINTENANCE", "ESTIMATE_REPAIR", "ESTIMATE_REPLACE", "INSTALL", "WARRANTY", "CALLBACK", "SALES", "UNKNOWN", null ] }, "required": false, "name": "job_class", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "uuid", "default": null, "description": "A currently validated credited company member." }, "required": false, "description": "A currently validated credited company member.", "name": "team_member_id", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "SOLD", "EARNED", null ] }, "required": false, "name": "credit_type", "in": "query" } ], "responses": { "200": { "description": "Successful read. Clients ignore unrecognized response fields.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueAttributionReportResponse" }, "example": { "data": [ { "period_start": "2026-08-01", "period_end": "2026-09-01", "currency": "USD", "group": { "dimension": "team_member", "value": null, "label": null }, "job_count": 1, "sold_credit_count": 1, "earned_credit_count": 0, "sold_revenue_cents": 0, "earned_revenue_cents": 0 }, { "period_start": "2026-08-01", "period_end": "2026-09-01", "currency": "USD", "group": { "dimension": "team_member", "value": "11111111-1111-4111-8111-000000000401", "label": "Alex Example" }, "job_count": 1, "sold_credit_count": 1, "earned_credit_count": 1, "sold_revenue_cents": 100000, "earned_revenue_cents": 100000 } ], "pagination": { "next_cursor": null }, "meta": { "request_id": "11111111-1111-4111-8111-000000009999", "generated_at": "2026-09-08T19:00:00Z", "timezone": "America/Los_Angeles" }, "report": { "start_date": "2026-08-01", "end_date": "2026-09-01", "bucket": "month", "group_by": "team_member", "date_basis": "WORK_COMPLETED" } } } } }, "400": { "description": "Malformed input, unknown query parameter, unsupported combination or invalid cursor.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "end_date must be later than start_date", "request_id": "example-request", "details": [] } } } } }, "401": { "description": "Missing, invalid or expired key, or invalid linked identity.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHENTICATED", "message": "A valid API key is required", "request_id": "example-request", "details": [] } } } } }, "404": { "description": "Missing resource or resource outside the authenticated company. Same response for both.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "example-request", "details": [] } } } } }, "405": { "description": "Write methods do not mutate business data and return 405.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Allow": { "schema": { "type": "string" }, "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "This resource supports GET", "request_id": "example-request", "details": [] } } } } }, "429": { "description": "Company request budget exhausted; retry after the indicated delay.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Request limit exceeded", "request_id": "example-request", "details": [] } } } } }, "500": { "description": "Unexpected failure. Share request_id with support; no stack or provider secrets in response.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "private, no-store" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Unable to complete request", "request_id": "example-request", "details": [] } } } } } } } } }, "externalDocs": { "description": "Breezy FSM reporting guides and API reference", "url": "https://developers.getbreezyapp.com" } }