{ "openapi": "3.1.0", "info": { "title": "Scopable API", "version": "1.0.0", "description": "The Scopable tenant API, version 1. Every operation here can be called with a Scopable API key and acts on the key's own workspace only. Requests and responses are validated against exactly these schemas. List operations are cursor-paged (limit 1 to 200, default 50); every error uses the ErrorEnvelope shape, and its `type` resolves to the schema here that describes its code; every command requires an Idempotency-Key header; limits are reported in RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers, and a refused call (429) carries Retry-After." }, "servers": [ { "url": "https://api.scopable.io" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/clients/filter-options": { "get": { "operationId": "client.filter_options", "summary": "List the client roster's filter options", "description": "Lists client roster filter choices in the caller's tenant. Signed-in users receive the distinct account types, owners, frameworks and exact status values displayed by visible clients across the full roster. API keys receive active account types, live people and scoped frameworks, with an empty statuses list. Each option is a value to filter on and the label to show.", "tags": [ "client" ], "parameters": [], "responses": { "200": { "description": "List the client roster's filter options", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountTypes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "owners": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "frameworks": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "accountTypes", "owners", "frameworks", "statuses" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/roster-counts": { "get": { "operationId": "client.roster_counts", "summary": "Count the client roster's tabs", "description": "Counts the caller's visible clients for each roster tab (all, active, at risk, sync issues, onboarding) under the same search and filters the roster applies. Search matches client name, contact, email, website, industry and city, plus clients whose owner or compliance framework matches. Filters are comma-separated lists. Use statusesJson, a JSON array, for status values containing commas.", "tags": [ "client" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "accountTypeIds", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "ownerIds", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "frameworkIds", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "statusesJson", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 101501 } } ], "responses": { "200": { "description": "Count the client roster's tabs", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "all": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "active": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "atRisk": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "syncIssues": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "onboarding": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "all", "active", "atRisk", "syncIssues", "onboarding" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/synced-count": { "get": { "operationId": "client.synced_count", "summary": "Count clients synced from a PSA", "description": "Counts the caller's clients that a ConnectWise or Halo source still claims and that are not archived.", "tags": [ "client" ], "parameters": [], "responses": { "200": { "description": "Count clients synced from a PSA", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "count" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/dashboard-summary": { "get": { "operationId": "client.dashboard_summary", "summary": "Get a client's overview card", "description": "Summarizes one client in the caller's tenant for its overview card: profile and owner, active monthly recurring revenue from agreements, open and recent quotes, the opportunity pipeline and win rate, compliance frameworks with their latest score and open gaps by severity, and SimpleSat CSAT/NPS over 90 days with its coverage. A client outside the tenant answers not_found. The client's status, logo and owner are null for an API key.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a client's overview card", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "primaryContactName": { "type": [ "string", "null" ] }, "primaryContactEmail": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "logoFilePath": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "industry", "primaryContactName", "primaryContactEmail", "phone", "website", "annualRevenue", "employeeCount", "status", "logoUrl", "logoFilePath" ], "additionalProperties": false }, "accountOwner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatarUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "financials": { "type": "object", "properties": { "activeMrr": { "type": "number" }, "activeAgreementCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "activeMrr", "activeAgreementCount" ], "additionalProperties": false }, "quotes": { "type": "object", "properties": { "openCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "openValue": { "type": "number" }, "recent": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "createdAt": { "type": [ "string", "null" ] }, "expirationDate": { "type": [ "string", "null" ] } }, "required": [ "name", "status", "salesStage", "amount", "createdAt", "expirationDate" ], "additionalProperties": false } } }, "required": [ "openCount", "openValue", "recent" ], "additionalProperties": false }, "opportunities": { "type": "object", "properties": { "openCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "wonCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lostCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "openPipelineValue": { "type": "number" }, "wonValue": { "type": "number" }, "winRate": { "type": [ "number", "null" ] } }, "required": [ "openCount", "wonCount", "lostCount", "openPipelineValue", "wonValue", "winRate" ], "additionalProperties": false }, "compliance": { "type": "object", "properties": { "frameworks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "version": { "type": "string" }, "score": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "version", "score" ], "additionalProperties": false } }, "averageScore": { "type": [ "number", "null" ] }, "openGapCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "gapsBySeverity": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "high": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medium": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "low": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "critical", "high", "medium", "low", "unknown" ], "additionalProperties": false } }, "required": [ "frameworks", "averageScore", "openGapCount", "gapsBySeverity" ], "additionalProperties": false }, "csatNps": { "anyOf": [ { "type": "object", "properties": { "lastResponseAt": { "type": [ "string", "null" ] }, "responseCount90d": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "csatAverage90d": { "type": [ "number", "null" ] }, "npsScore90d": { "type": [ "number", "null" ] }, "sentimentBreakdown": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mixed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown" ], "additionalProperties": false } }, "required": [ "lastResponseAt", "responseCount90d", "csatAverage90d", "npsScore90d", "sentimentBreakdown" ], "additionalProperties": false }, { "type": "null" } ] }, "sourceCoverage": { "type": "object", "properties": { "csat": { "type": "object", "properties": { "available": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string", "const": "simplesat" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "not_configured", "not_mapped", "no_data", "available", "stale", "sync_failed" ] }, "reason": { "type": "string" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "lastErrorAt": { "type": [ "string", "null" ] } }, "required": [ "available", "provider", "status", "reason", "lastSyncedAt", "lastErrorAt" ], "additionalProperties": false }, "projects": { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "type": "string" } }, "required": [ "available", "reason" ], "additionalProperties": false } }, "required": [ "csat", "projects" ], "additionalProperties": false } }, "required": [ "generatedAt", "client", "accountOwner", "financials", "quotes", "opportunities", "compliance", "csatNps", "sourceCoverage" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/ai-overview": { "get": { "operationId": "client.ai_overview_get", "summary": "Get a client's cached AI briefing", "description": "Reads the most recently generated AI briefing for one client in the caller's tenant, with the web sources it cited, or null when none has been generated. A client outside the tenant answers not_found. Generating a briefing is not part of this operation.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a client's cached AI briefing", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "briefing": { "type": "string" }, "generatedAt": { "type": "string" }, "generatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "promptVersion": { "type": "string" }, "sourceMetadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "webSearchSources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "pageAge": { "type": [ "string", "null" ] }, "toolUseId": { "type": "string" } }, "required": [ "url", "title", "domain", "pageAge", "toolUseId" ], "additionalProperties": false } } }, "required": [ "id", "tenantId", "clientId", "briefing", "generatedAt", "generatedBy", "promptVersion", "sourceMetadata", "webSearchSources" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "overview" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients": { "get": { "operationId": "client.list", "summary": "List clients", "description": "Pages through the clients in the caller's tenant, newest name-independent order: sorted by id so a cursor is stable while rows are written. Archived clients and clients a source has removed are excluded.", "tags": [ "client" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "List clients", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "client.create", "summary": "Create a client", "description": "Creates a client in the caller's tenant, optionally with its primary contact and default location in the same step. An active client with the same name (ignoring case) answers conflict. A primary contact needs a name, or a first or last name.", "tags": [ "client" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1000 }, "industry": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "employeeCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "faxNumber": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "cwCompanyTypes": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "required": [ "name" ], "additionalProperties": false }, "primaryContact": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "additionalProperties": false }, "defaultLocation": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "Create a client", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "primaryContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "defaultSiteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": [ "client", "primaryContactId", "defaultSiteId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}": { "get": { "operationId": "client.get", "summary": "Get a client", "description": "Reads one client by id from the caller's tenant. An id that belongs to another tenant answers not_found; existence is never leaked across tenants.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a client", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "client.update", "summary": "Update a client", "description": "Updates one or more profile fields of an existing client in the caller's tenant. A field left out of the request is unchanged; a field sent as null clears it. Reassigning the client's default contact is contact.set_default's job, not this operation's. For a ConnectWise-sourced client with write-back enabled, a value ConnectWise would reject answers conflict and writes nothing; otherwise a queued sync is reported as crmWriteBackEnqueued. A client id outside the tenant or that does not exist answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "website": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Update a client", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "crmWriteBackEnqueued": { "type": "boolean" } }, "required": [ "client", "crmWriteBackEnqueued" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/summary": { "get": { "operationId": "client.summary", "summary": "Get a client summary", "description": "Reads an overview of one client: its profile, how many contacts and open opportunities it has, and its five most recent quotes. The counts are of the rows contact.search and opportunity.search would return, so they never exceed what the same caller can retrieve. A hidden client answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a client summary", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "industry", "employeeCount", "website", "phone", "createdAt" ], "additionalProperties": false }, "openOpportunities": { "type": "number" }, "totalContacts": { "type": "number" }, "recentQuotes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "totalAmount": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "totalAmount", "createdAt" ], "additionalProperties": false } } }, "required": [ "client", "openOpportunities", "totalContacts", "recentQuotes" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/brief": { "get": { "operationId": "client.brief", "summary": "Get a client brief", "description": "A composed read of what an account manager needs about one client in a single call: the client record, agreements by next renewal, recent service tickets and projects with open work first, sites, contacts with the primary first, open opportunities, a configuration count and sample, and the service health rollup, each with its own freshness timestamp so a caller can flag stale data. Every section applies the same visibility rule its own operation does, so the brief can never return a row that operation refuses. The tickets section carries service records only and the projects section project records only, so neither is a subset of the other. Documentation reports itself unavailable: its source is published to no caller on this deployment. Deterministic from its inputs, and capped rather than paged; a caller needing a full list asks that domain's own operation. Because it composes nine domains, a key must hold every one of their read scopes, not client:read alone. A hidden client answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a client brief", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "generatedAt": { "type": "string" }, "agreements": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "renewalDate": { "type": [ "string", "null" ] }, "autoRenewal": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "status", "startDate", "endDate", "renewalDate", "autoRenewal" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "tickets": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "summary": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "closedFlag": { "type": "boolean" }, "dateEntered": { "type": [ "string", "null" ] }, "closedDate": { "type": [ "string", "null" ] } }, "required": [ "id", "summary", "status", "priority", "closedFlag", "dateEntered", "closedDate" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "projects": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "string", "null" ] }, "targetDate": { "type": [ "string", "null" ] }, "closedFlag": { "type": "boolean" } }, "required": [ "id", "name", "status", "ownerName", "openedAt", "targetDate", "closedFlag" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "sites": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" } }, "required": [ "id", "name", "city", "state", "isDefault" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "contacts": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "isPrimaryContact": { "type": "boolean" } }, "required": [ "id", "name", "title", "email", "isPrimaryContact" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "opportunities": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "expectedCloseDate": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "status", "expectedCloseDate" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "items", "freshness" ], "additionalProperties": false }, "configurations": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "activeCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "configurationType": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "configurationType", "status" ], "additionalProperties": false } } }, "required": [ "totalCount", "activeCount", "items" ], "additionalProperties": false }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "summary", "freshness" ], "additionalProperties": false }, "documentation": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "available", "unavailable" ] }, "unavailableReason": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "artifactKind": { "type": "string" }, "sourceObservedAt": { "type": [ "string", "null" ] }, "ageDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "title", "artifactKind", "sourceObservedAt", "ageDays" ], "additionalProperties": false } }, "freshness": { "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] } }, "required": [ "asOf" ], "additionalProperties": false } }, "required": [ "availability", "unavailableReason", "items", "freshness" ], "additionalProperties": false }, "serviceHealth": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "windowStart": { "type": "string" }, "windowEnd": { "type": "string" }, "narrative": { "anyOf": [ { "type": "object", "properties": { "headline": { "type": "string" }, "narrative": { "type": "string" }, "recommendedFocus": { "type": "array", "items": { "type": "string" } }, "ticketCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "windowStart": { "type": "string" }, "windowEnd": { "type": "string" }, "generatedAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "headline", "narrative", "recommendedFocus", "ticketCount", "windowStart", "windowEnd", "generatedAt", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "rollup": { "type": "object", "properties": { "ticketCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "averageSentimentScore": { "type": [ "number", "null" ] }, "sentimentLabelCounts": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mixed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative", "mixed" ], "additionalProperties": false }, "riskFlagCounts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "latestSentimentScore": { "type": [ "number", "null" ] }, "latestSentimentLabel": { "type": [ "string", "null" ] }, "latestTrajectory": { "type": [ "string", "null" ] }, "trend": { "type": "array", "items": { "type": "object", "properties": { "ticketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "dateEntered": { "type": [ "string", "null" ] }, "windowDate": { "type": "string" }, "analyzedAt": { "type": "string" }, "sentimentScore": { "type": "number" }, "sentimentLabel": { "type": "string" }, "trajectory": { "type": "string" }, "riskFlags": { "type": "array", "items": { "type": "string" } } }, "required": [ "ticketId", "dateEntered", "windowDate", "analyzedAt", "sentimentScore", "sentimentLabel", "trajectory", "riskFlags" ], "additionalProperties": false } }, "trendTruncated": { "type": "boolean" } }, "required": [ "ticketCount", "averageSentimentScore", "sentimentLabelCounts", "riskFlagCounts", "latestSentimentScore", "latestSentimentLabel", "latestTrajectory", "trend", "trendTruncated" ], "additionalProperties": false }, "freshness": { "type": "object", "properties": { "narrativeGeneratedAt": { "type": [ "string", "null" ] }, "rollupComputedAt": { "type": "string" } }, "required": [ "narrativeGeneratedAt", "rollupComputedAt" ], "additionalProperties": false } }, "required": [ "clientId", "windowStart", "windowEnd", "narrative", "rollup", "freshness" ], "additionalProperties": false } }, "required": [ "client", "generatedAt", "agreements", "tickets", "projects", "sites", "contacts", "opportunities", "configurations", "documentation", "serviceHealth" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/sentiment": { "get": { "operationId": "client.sentiment", "summary": "Get a client sentiment snapshot", "description": "Reads a computed sentiment snapshot for one client: a bucket, a confidence, evidence counts, the top drivers, risk flags and suggested next actions, derived with deterministic local rules from the client's recent CRM activities, opportunities and quotes. All of that text moves the score, but an evidence snippet quotes only text another published read already returns, so an email body, a meeting transcript summary, an opportunity's notes and a quote's description or loss reason are scored and never quoted. Contacts and opportunities are read through the same visibility rules contact.search and opportunity.search apply. A key needs opportunity:read as well as client:read, because the snapshot returns opportunity and quote titles. A hidden client answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "windowDays", "in": "query", "required": false, "schema": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Get a client sentiment snapshot", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "industry", "website", "phone" ], "additionalProperties": false }, "bucket": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed", "unknown" ] }, "confidence": { "type": "number" }, "generatedAt": { "type": "string" }, "windowDays": { "type": "number" }, "reason": { "type": [ "string", "null" ] }, "evidenceCounts": { "type": "object", "properties": { "activities": { "type": "number" }, "usableActivities": { "type": "number" }, "opportunities": { "type": "number" }, "quotes": { "type": "number" }, "positiveSignals": { "type": "number" }, "negativeSignals": { "type": "number" }, "neutralSignals": { "type": "number" } }, "required": [ "activities", "usableActivities", "opportunities", "quotes", "positiveSignals", "negativeSignals", "neutralSignals" ], "additionalProperties": false }, "topDrivers": { "type": "array", "items": { "type": "string" } }, "riskFlags": { "type": "array", "items": { "type": "string" } }, "nextActions": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "sourceType": { "type": "string", "enum": [ "activity", "opportunity", "quote" ] }, "entityType": { "type": "string", "enum": [ "client", "contact", "opportunity", "quote" ] }, "entityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "date": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "signal": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "score": { "type": "number" } }, "required": [ "sourceType", "entityType", "entityId", "date", "title", "snippet", "signal", "score" ], "additionalProperties": false } } }, "required": [ "client", "bucket", "confidence", "generatedAt", "windowDays", "reason", "evidenceCounts", "topDrivers", "riskFlags", "nextActions", "evidence" ], "additionalProperties": false }, "markdown": { "type": "string" } }, "required": [ "snapshot", "markdown" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/profile": { "post": { "operationId": "client.profile_update", "summary": "Update a client's profile", "description": "Updates a client's profile fields, and optionally its primary contact and default location, in one step. A field left out is unchanged; null clears it. A contact or site id that is not this client's answers not_found; a name another active client already has answers conflict. For a ConnectWise-sourced record with write-back enabled, a value ConnectWise would reject answers conflict and writes nothing; otherwise each queued sync is reported in crmWriteBack.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fields": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 1000 }, "industry": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "employeeCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "faxNumber": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "cwCompanyTypes": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "additionalProperties": false }, "primaryContact": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "additionalProperties": false }, "defaultLocation": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "additionalProperties": false } } } } } }, "responses": { "200": { "description": "Update a client's profile", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "primaryContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "defaultSiteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "crmWriteBack": { "type": "object", "properties": { "client": { "type": "boolean" }, "primaryContact": { "type": "boolean" }, "defaultLocation": { "type": "boolean" } }, "required": [ "client", "primaryContact", "defaultLocation" ], "additionalProperties": false } }, "required": [ "client", "primaryContactId", "defaultSiteId", "crmWriteBack" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/default-contact/clear": { "post": { "operationId": "client.default_contact_clear", "summary": "Clear a client's preferred contact", "description": "Leaves a client with no preferred contact; the former one is no longer marked primary. A client with none answers cleared: false. A client id outside the tenant, archived, or that does not exist answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Clear a client's preferred contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "cleared": { "type": "boolean" } }, "required": [ "client", "cleared" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/logo": { "post": { "operationId": "client.logo_set", "summary": "Set a client's logo", "description": "Records an uploaded image as a client's logo. The file path must be the caller's tenant id, then the client id, then the file name, and the URL must be the HTTPS client-logos storage URL of that same path. A client id outside the tenant, archived, or that does not exist answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "logoFilePath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "logoUrl": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "logoFilePath", "logoUrl" ] } } } }, "responses": { "200": { "description": "Set a client's logo", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false }, "logoUrl": { "type": "string" }, "logoFilePath": { "type": "string" } }, "required": [ "client", "logoUrl", "logoFilePath" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/logo/clear": { "post": { "operationId": "client.logo_clear", "summary": "Clear a client's logo", "description": "Removes a client's logo. A client with none answers the same way. A client id outside the tenant, archived, or that does not exist answers not_found.", "tags": [ "client" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Clear a client's logo", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "number", "null" ] }, "annualRevenue": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "website", "industry", "phone", "contactEmail", "contactName", "address", "addressLine2", "city", "state", "zipCode", "country", "employeeCount", "annualRevenue", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "client" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/bulk-archive": { "post": { "operationId": "contact.bulk_archive", "summary": "Archive every contact a list filter matches", "description": "Archives the active contacts in the caller's tenant that match the contact list's client, search and filters, minus any excluded ids. Each archived contact stops being primary, a client whose preferred contact it was is left without one, and when ConnectWise write-back is on its deletion is queued there. More than 5,000 matches answers validation_failed and archives nothing; narrow the filters and try again.", "tags": [ "contact" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "search": { "type": "string", "maxLength": 200 }, "filters": { "type": "object", "properties": { "account": { "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 500 } }, "title": { "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 500 } }, "contactType": { "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 500 } } }, "additionalProperties": false }, "excludedIds": { "maxItems": 5000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } } } } } }, "responses": { "200": { "description": "Archive every contact a list filter matches", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "archivedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "archivedCount" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/search": { "get": { "operationId": "contact.search", "summary": "Search contacts", "description": "Searches contacts across all clients, or within one client, in the caller's tenant. Matches on name and email. Excluded: a contact that is archived, that every linked source reports removed, that the PSA has marked inactive, and any contact whose client is itself hidden. Each contact's url opens the parent client's page, because contacts have no detail page of their own. Ordered by name with the contact id as tiebreaker and paged with an opaque cursor.", "tags": [ "contact" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Search contacts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/{contactId}/restore": { "post": { "operationId": "contact.restore", "summary": "Restore an archived contact", "description": "Clears one contact's archive in the caller's tenant. Does not restore default or primary status. A contact that is not archived answers with its current state rather than an error, and a contact id outside the tenant or that does not exist answers not_found.", "tags": [ "contact" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Restore an archived contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false } }, "required": [ "contact" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/{contactId}/archive": { "post": { "operationId": "contact.archive", "summary": "Archive a contact", "description": "Soft-deletes one contact in the caller's tenant: clears its primary-contact flag, and clears the client's default-contact pointer if this contact held it. A contact that is already archived answers with its current state rather than an error. A contact id outside the tenant or that does not exist answers not_found.", "tags": [ "contact" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Archive a contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false }, "defaultContactCleared": { "type": "boolean" } }, "required": [ "contact", "defaultContactCleared" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/{contactId}/set-default": { "post": { "operationId": "contact.set_default", "summary": "Set a client's default contact", "description": "Makes an existing contact the client's default contact, the one quotes and other commercial workflows fall back to. The previous default contact stops being primary. An archived contact, or a contact whose client is archived, answers conflict and changes nothing. A contact id outside the tenant or that does not exist answers not_found.", "tags": [ "contact" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Set a client's default contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "contact", "clientId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts": { "post": { "operationId": "contact.create", "summary": "Create a contact", "description": "Creates a new contact under a client in the caller's tenant. If the client has no default contact yet, the new contact is promoted to it automatically, best-effort -- a promotion failure does not fail the create. A client id outside the tenant, archived, or that does not exist answers not_found; a site id that does not belong to the same client answers conflict.", "tags": [ "contact" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1 }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "email": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "mobilePhone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "preferredContactMethod": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "contactType": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "clientId", "name" ] } } } }, "responses": { "200": { "description": "Create a contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false } }, "required": [ "contact" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/{contactId}": { "post": { "operationId": "contact.update", "summary": "Update a contact", "description": "Updates one or more fields of an existing contact in the caller's tenant. A field left out of the request is unchanged; a field sent as null clears it. Does not change which contact is the client's default. Use contact.set_default for that. Actual edits to ConnectWise-owned fields answer conflict and write nothing unless write-back is enabled and supports every owned edit. A value ConnectWise would reject, an inconsistent derived name, or a write-back request that cannot be accepted also refuses the entire edit. Local preferences and communications without a populated provider value remain writable. Unchanged values do not request write-back. crmWriteBackEnqueued reports whether a ConnectWise update was requested, not whether it has completed. A contact id outside the tenant, archived, or that does not exist answers not_found; a site id that does not belong to the same client answers conflict. avatarUrl must be a link to a photo uploaded for this same contact in the caller's workspace, or null to remove it; it is accepted from a user session only, and an API key that sends it answers forbidden.", "tags": [ "contact" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "firstName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "mobilePhone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "preferredContactMethod": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "contactType": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Update a contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "title", "isPrimary", "clientId", "clientName", "url" ], "additionalProperties": false }, "crmWriteBackEnqueued": { "type": "boolean" } }, "required": [ "contact", "crmWriteBackEnqueued" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "get": { "operationId": "contact.get", "summary": "Get a contact", "description": "Reads one active contact in the caller's tenant with its client: the split name, every phone and email, the address, department, contact preferences and defaults. An archived contact, one whose client is hidden, and one in another tenant answer not_found. PSA mirror ids, private phone numbers, custom fields and sync bookkeeping are null for an API key.", "tags": [ "contact" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a contact", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "nickName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "mobilePhone": { "type": [ "string", "null" ] }, "directPhone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "contactType": { "type": [ "string", "null" ] }, "contactTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "doNotContact": { "type": [ "boolean", "null" ] }, "preferredContactMethod": { "type": [ "string", "null" ] }, "emailSourceStatus": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "systemLocationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "systemLocationKind": { "type": "string" }, "managerContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "assistantContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "isPrimaryContact": { "type": [ "boolean", "null" ] }, "isDefaultBillingContact": { "type": [ "boolean", "null" ] }, "isDefaultCompanyContact": { "type": [ "boolean", "null" ] }, "relationshipOverride": { "type": [ "string", "null" ] }, "sourcePresence": { "type": "string" }, "cwInactiveFlag": { "type": [ "boolean", "null" ] }, "cwRelationship": { "type": [ "string", "null" ] }, "cwContactTypes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "connectwiseContactId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSiteId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cwCompanyLocationId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cwManagerContactId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cwAssistantContactId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloContactId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "itglueContactId": { "type": [ "string", "null" ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "haloSyncStatus": { "type": [ "string", "null" ] }, "crmWritebackRevision": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseCreateRequested": { "type": [ "boolean", "null" ] }, "connectwiseDeleteRequested": { "type": [ "boolean", "null" ] }, "communicationItems": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "lastSyncedAt": { "type": [ "string", "null" ] }, "externalUpdatedAt": { "type": [ "string", "null" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "lastSeenPsaSyncJobId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "orphanedAt": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "archivedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "archivedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "tenantId", "clientId", "clientName", "name", "firstName", "lastName", "nickName", "email", "phone", "mobilePhone", "directPhone", "title", "department", "contactType", "contactTypeId", "linkedinUrl", "doNotContact", "preferredContactMethod", "emailSourceStatus", "avatarUrl", "address", "addressLine2", "city", "state", "zipCode", "country", "siteId", "systemLocationId", "systemLocationKind", "managerContactId", "assistantContactId", "isPrimaryContact", "isDefaultBillingContact", "isDefaultCompanyContact", "relationshipOverride", "sourcePresence", "cwInactiveFlag", "cwRelationship", "cwContactTypes", "connectwiseContactId", "connectwiseSiteId", "cwCompanyLocationId", "cwManagerContactId", "cwAssistantContactId", "haloContactId", "itglueContactId", "connectwiseSyncStatus", "haloSyncStatus", "crmWritebackRevision", "connectwiseCreateRequested", "connectwiseDeleteRequested", "communicationItems", "customFields", "lastSyncedAt", "externalUpdatedAt", "lastSeenAt", "lastSeenPsaSyncJobId", "orphanedAt", "createdBy", "archivedBy", "archivedAt", "createdAt", "updatedAt", "client" ], "additionalProperties": false } }, "required": [ "contact" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/contacts/filter-options": { "get": { "operationId": "contact.filter_options", "summary": "List the contact roster's filter options", "description": "Lists the distinct contact types, titles and client names across the caller's contacts, or one client's, for the contact roster's filter menus. A client outside the tenant answers not_found.", "tags": [ "contact" ], "parameters": [ { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "List the contact roster's filter options", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactTypes": { "type": "array", "items": { "type": "string" } }, "titles": { "type": "array", "items": { "type": "string" } }, "accounts": { "type": "array", "items": { "type": "string" } } }, "required": [ "contactTypes", "titles", "accounts" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/roster": { "get": { "operationId": "opportunity.roster", "summary": "Page through the opportunity roster", "description": "Pages through the opportunities in the caller's tenant as the Opportunities screen lists them, most recently updated first unless sorted by creation time, with the id as tiebreaker, paged with an opaque cursor. Search matches title and description; stage, owner and status narrow the list, and status is not filtered unless asked for. Each row is the same record opportunity.detail returns. An opportunity whose client is hidden, and one the PSA no longer backs, are excluded. customFields, the ConnectWise write-back status and error, and the client's logo and ConnectWise id are null for an API key.", "tags": [ "opportunity" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "stageId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "ownerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived", "deleted", "open" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "-updatedAt", "-createdAt" ] } } ], "responses": { "200": { "description": "Page through the opportunity roster", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "tenantName": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "opportunityTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedQuoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "probability": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "actualCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "forecastedValueServices": { "type": [ "number", "null" ] }, "forecastedValueProducts": { "type": [ "number", "null" ] }, "forecastedValueRecurring": { "type": [ "number", "null" ] }, "forecastedTcv": { "type": [ "number", "null" ] }, "forecastedMrr": { "type": [ "number", "null" ] }, "forecastedArr": { "type": [ "number", "null" ] }, "wonValueServices": { "type": [ "number", "null" ] }, "wonValueProducts": { "type": [ "number", "null" ] }, "wonValueRecurring": { "type": [ "number", "null" ] }, "wonTcv": { "type": [ "number", "null" ] }, "wonMrr": { "type": [ "number", "null" ] }, "wonArr": { "type": [ "number", "null" ] }, "lostValueServices": { "type": [ "number", "null" ] }, "lostValueProducts": { "type": [ "number", "null" ] }, "lostValueRecurring": { "type": [ "number", "null" ] }, "lostTcv": { "type": [ "number", "null" ] }, "lostMrr": { "type": [ "number", "null" ] }, "lostArr": { "type": [ "number", "null" ] }, "businessUnit": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "decisionCriteria": { "type": [ "string", "null" ] }, "timelineNotes": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "primarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "primarySalesRepName": { "type": [ "string", "null" ] }, "secondarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "secondarySalesRepName": { "type": [ "string", "null" ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackError": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "opportunityType": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "stageOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isClosedWon": { "type": [ "boolean", "null" ] }, "isClosedLost": { "type": [ "boolean", "null" ] }, "isArchived": { "type": [ "boolean", "null" ] }, "archivedReason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sourceIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "name", "description", "stageOrder", "color", "icon", "isDefault", "isClosedWon", "isClosedLost", "isArchived", "archivedReason", "source", "sourceIntegrationId", "createdAt", "updatedAt" ], "additionalProperties": false }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "connectwiseAccountId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "logoUrl", "connectwiseAccountId" ], "additionalProperties": false }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "billingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "shippingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "clientId", "addressLine1", "addressLine2", "city", "state", "zip", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "title", "description", "status", "clientId", "clientName", "tenantName", "contactId", "billingContactId", "shippingContactId", "siteId", "stageId", "ownerId", "opportunityTypeId", "linkedQuoteId", "probability", "expectedCloseDate", "actualCloseDate", "forecastedValueServices", "forecastedValueProducts", "forecastedValueRecurring", "forecastedTcv", "forecastedMrr", "forecastedArr", "wonValueServices", "wonValueProducts", "wonValueRecurring", "wonTcv", "wonMrr", "wonArr", "lostValueServices", "lostValueProducts", "lostValueRecurring", "lostTcv", "lostMrr", "lostArr", "businessUnit", "source", "decisionCriteria", "timelineNotes", "notes", "tags", "customFields", "primarySalesRepId", "primarySalesRepName", "secondarySalesRepId", "secondarySalesRepName", "connectwiseOpportunityId", "haloOpportunityId", "connectwiseSyncStatus", "connectwiseWritebackStatus", "connectwiseWritebackError", "createdBy", "updatedBy", "createdAt", "updatedAt", "opportunityType", "stage", "client", "owner", "contact", "billingContact", "shippingContact", "site" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/probability-options": { "get": { "operationId": "opportunity.probability_options", "summary": "List the tenant's ConnectWise opportunity probabilities", "description": "Lists the probability values ConnectWise accepts for the caller's tenant, lowest first, and whether an active ConnectWise integration exists. An empty list with connected false means free-form probability is correct; with connected true the vocabulary has not synced.", "tags": [ "opportunity" ], "parameters": [], "responses": { "200": { "description": "List the tenant's ConnectWise opportunity probabilities", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "probabilities": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } }, "connected": { "type": "boolean" } }, "required": [ "probabilities", "connected" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}/detail": { "get": { "operationId": "opportunity.detail", "summary": "Get an opportunity record", "description": "Reads one opportunity in the caller's tenant as the opportunity page renders it: every forecast, won and lost value, the sales reps, and the joined stage, client, owner, contacts, site and type. An id in another tenant, on a hidden client, or that the PSA no longer backs answers not_found. customFields, the ConnectWise write-back status and error, and the client's logo and ConnectWise id are null for an API key.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get an opportunity record", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "tenantName": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "opportunityTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedQuoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "probability": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "actualCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "forecastedValueServices": { "type": [ "number", "null" ] }, "forecastedValueProducts": { "type": [ "number", "null" ] }, "forecastedValueRecurring": { "type": [ "number", "null" ] }, "forecastedTcv": { "type": [ "number", "null" ] }, "forecastedMrr": { "type": [ "number", "null" ] }, "forecastedArr": { "type": [ "number", "null" ] }, "wonValueServices": { "type": [ "number", "null" ] }, "wonValueProducts": { "type": [ "number", "null" ] }, "wonValueRecurring": { "type": [ "number", "null" ] }, "wonTcv": { "type": [ "number", "null" ] }, "wonMrr": { "type": [ "number", "null" ] }, "wonArr": { "type": [ "number", "null" ] }, "lostValueServices": { "type": [ "number", "null" ] }, "lostValueProducts": { "type": [ "number", "null" ] }, "lostValueRecurring": { "type": [ "number", "null" ] }, "lostTcv": { "type": [ "number", "null" ] }, "lostMrr": { "type": [ "number", "null" ] }, "lostArr": { "type": [ "number", "null" ] }, "businessUnit": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "decisionCriteria": { "type": [ "string", "null" ] }, "timelineNotes": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "primarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "primarySalesRepName": { "type": [ "string", "null" ] }, "secondarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "secondarySalesRepName": { "type": [ "string", "null" ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackError": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "opportunityType": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "stageOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isClosedWon": { "type": [ "boolean", "null" ] }, "isClosedLost": { "type": [ "boolean", "null" ] }, "isArchived": { "type": [ "boolean", "null" ] }, "archivedReason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sourceIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "name", "description", "stageOrder", "color", "icon", "isDefault", "isClosedWon", "isClosedLost", "isArchived", "archivedReason", "source", "sourceIntegrationId", "createdAt", "updatedAt" ], "additionalProperties": false }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "connectwiseAccountId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "logoUrl", "connectwiseAccountId" ], "additionalProperties": false }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "billingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "shippingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "clientId", "addressLine1", "addressLine2", "city", "state", "zip", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "title", "description", "status", "clientId", "clientName", "tenantName", "contactId", "billingContactId", "shippingContactId", "siteId", "stageId", "ownerId", "opportunityTypeId", "linkedQuoteId", "probability", "expectedCloseDate", "actualCloseDate", "forecastedValueServices", "forecastedValueProducts", "forecastedValueRecurring", "forecastedTcv", "forecastedMrr", "forecastedArr", "wonValueServices", "wonValueProducts", "wonValueRecurring", "wonTcv", "wonMrr", "wonArr", "lostValueServices", "lostValueProducts", "lostValueRecurring", "lostTcv", "lostMrr", "lostArr", "businessUnit", "source", "decisionCriteria", "timelineNotes", "notes", "tags", "customFields", "primarySalesRepId", "primarySalesRepName", "secondarySalesRepId", "secondarySalesRepName", "connectwiseOpportunityId", "haloOpportunityId", "connectwiseSyncStatus", "connectwiseWritebackStatus", "connectwiseWritebackError", "createdBy", "updatedBy", "createdAt", "updatedAt", "opportunityType", "stage", "client", "owner", "contact", "billingContact", "shippingContact", "site" ], "additionalProperties": false } }, "required": [ "opportunity" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/opportunities": { "get": { "operationId": "opportunity.list", "summary": "List a client's opportunities", "description": "Lists one client's opportunities in the caller's tenant, newest first by creation time with the id as tiebreaker, paged with an opaque cursor (default page 50). Each row is the same record opportunity.detail returns. A client in another tenant answers not_found; an archived client answers an empty page.", "tags": [ "opportunity" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "List a client's opportunities", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "tenantName": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "opportunityTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedQuoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "probability": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "actualCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "forecastedValueServices": { "type": [ "number", "null" ] }, "forecastedValueProducts": { "type": [ "number", "null" ] }, "forecastedValueRecurring": { "type": [ "number", "null" ] }, "forecastedTcv": { "type": [ "number", "null" ] }, "forecastedMrr": { "type": [ "number", "null" ] }, "forecastedArr": { "type": [ "number", "null" ] }, "wonValueServices": { "type": [ "number", "null" ] }, "wonValueProducts": { "type": [ "number", "null" ] }, "wonValueRecurring": { "type": [ "number", "null" ] }, "wonTcv": { "type": [ "number", "null" ] }, "wonMrr": { "type": [ "number", "null" ] }, "wonArr": { "type": [ "number", "null" ] }, "lostValueServices": { "type": [ "number", "null" ] }, "lostValueProducts": { "type": [ "number", "null" ] }, "lostValueRecurring": { "type": [ "number", "null" ] }, "lostTcv": { "type": [ "number", "null" ] }, "lostMrr": { "type": [ "number", "null" ] }, "lostArr": { "type": [ "number", "null" ] }, "businessUnit": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "decisionCriteria": { "type": [ "string", "null" ] }, "timelineNotes": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "primarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "primarySalesRepName": { "type": [ "string", "null" ] }, "secondarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "secondarySalesRepName": { "type": [ "string", "null" ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackError": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "opportunityType": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "stageOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isClosedWon": { "type": [ "boolean", "null" ] }, "isClosedLost": { "type": [ "boolean", "null" ] }, "isArchived": { "type": [ "boolean", "null" ] }, "archivedReason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sourceIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "name", "description", "stageOrder", "color", "icon", "isDefault", "isClosedWon", "isClosedLost", "isArchived", "archivedReason", "source", "sourceIntegrationId", "createdAt", "updatedAt" ], "additionalProperties": false }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "connectwiseAccountId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "logoUrl", "connectwiseAccountId" ], "additionalProperties": false }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "billingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "shippingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "clientId", "addressLine1", "addressLine2", "city", "state", "zip", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "title", "description", "status", "clientId", "clientName", "tenantName", "contactId", "billingContactId", "shippingContactId", "siteId", "stageId", "ownerId", "opportunityTypeId", "linkedQuoteId", "probability", "expectedCloseDate", "actualCloseDate", "forecastedValueServices", "forecastedValueProducts", "forecastedValueRecurring", "forecastedTcv", "forecastedMrr", "forecastedArr", "wonValueServices", "wonValueProducts", "wonValueRecurring", "wonTcv", "wonMrr", "wonArr", "lostValueServices", "lostValueProducts", "lostValueRecurring", "lostTcv", "lostMrr", "lostArr", "businessUnit", "source", "decisionCriteria", "timelineNotes", "notes", "tags", "customFields", "primarySalesRepId", "primarySalesRepName", "secondarySalesRepId", "secondarySalesRepName", "connectwiseOpportunityId", "haloOpportunityId", "connectwiseSyncStatus", "connectwiseWritebackStatus", "connectwiseWritebackError", "createdBy", "updatedBy", "createdAt", "updatedAt", "opportunityType", "stage", "client", "owner", "contact", "billingContact", "shippingContact", "site" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/quote-status-sync": { "post": { "operationId": "opportunity.quote_status_sync", "summary": "Move an opportunity to match its quote's status", "description": "Moves the opportunity linked to one of the caller's tenant's quotes to the stage and probability its status implies: sent to the quote stage at 75%, approved or signed to closed won at 100%, rejected or expired to closed lost at 0%. Answers the opportunity moved, or null when nothing changed. A quote outside the tenant answers not_found. Requires edit_existing_opportunities.", "tags": [ "opportunity" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "quoteStatus": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "quoteId", "quoteStatus" ] } } } }, "responses": { "200": { "description": "Move an opportunity to match its quote's status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": [ "opportunityId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}/linked-quote": { "get": { "operationId": "opportunity.linked_quote_get", "summary": "Get an opportunity's linked quote", "description": "Reads the quote linked to one opportunity in the caller's tenant, or null when none is linked. An opportunity outside the tenant, on a hidden client, or that the PSA no longer backs answers not_found.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get an opportunity's linked quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "totalAmount": { "type": [ "number", "null" ] }, "value": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "title", "status", "totalAmount", "value", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quote" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}/quote": { "post": { "operationId": "opportunity.quote_create", "summary": "Create a quote from an opportunity", "description": "Creates a draft quote seeded from one opportunity in the caller's tenant, links it, and moves the opportunity to the workspace's first quote or proposal stage at 75% probability when one exists. These changes succeed or fail together. An opportunity outside the tenant answers not_found; one that already has a linked quote answers conflict. Requires create_quotes, edit_existing_opportunities and change_quote_pricing.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Create a quote from an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "quoteId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}/quote-link": { "post": { "operationId": "opportunity.quote_link", "summary": "Link a quote to an opportunity", "description": "Points one opportunity in the caller's tenant at one of the tenant's quotes. An opportunity or quote outside the tenant answers not_found. Requires edit_existing_opportunities.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "quoteId" ] } } } }, "responses": { "200": { "description": "Link a quote to an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "opportunityId", "quoteId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}/quote-unlink": { "post": { "operationId": "opportunity.quote_unlink", "summary": "Unlink a quote from an opportunity", "description": "Clears the link between one opportunity and one quote in the caller's tenant, on both records. If the opportunity has another quote, it becomes the linked one. An opportunity or quote outside the tenant answers not_found. Requires edit_existing_opportunities.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "quoteId" ] } } } }, "responses": { "200": { "description": "Unlink a quote from an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "unlinked": { "type": "boolean", "const": true } }, "required": [ "unlinked" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/search": { "get": { "operationId": "opportunity.search", "summary": "Search opportunities", "description": "Searches opportunities in the caller's tenant by name, status, or client. An opportunity whose client is hidden, and one the PSA no longer backs, are excluded; status is not filtered unless asked for, so an archived or deleted opportunity is returned until the caller narrows it. Ordered newest first by creation time with the opportunity id as tiebreaker and paged with an opaque cursor.", "tags": [ "opportunity" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived", "deleted", "open" ] } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Search opportunities", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "stage": { "type": "string" }, "stageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "estimatedValue": { "type": "number" }, "closeDate": { "type": [ "string", "null" ] }, "clientName": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "stage", "stageId", "estimatedValue", "closeDate", "clientName", "clientId", "clientUrl", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/metrics": { "get": { "operationId": "opportunity.metrics", "summary": "Get opportunity pipeline metrics", "description": "Computes win rate, average deal size, average time to close and a per-stage value distribution over the caller's tenant's active, PSA-present opportunities, optionally narrowed to a created-at date range. Every pipeline stage lists in stageDistribution even when no opportunity in range is in it, at zero.", "tags": [ "opportunity" ], "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "Get opportunity pipeline metrics", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "totalOpportunities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalValue": { "type": "number" }, "avgDealSize": { "type": "number" }, "avgTimeToClose": { "type": "number" }, "winRate": { "type": "number" }, "lossRate": { "type": "number" }, "activeOpportunities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closedWonOpportunities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closedLostOpportunities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pipelineValue": { "type": "number" }, "stageDistribution": { "type": "array", "items": { "type": "object", "properties": { "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stageName": { "type": "string" }, "stageColor": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalValue": { "type": "number" }, "averageValue": { "type": "number" }, "averageDaysInStage": { "type": "number" } }, "required": [ "stageId", "stageName", "stageColor", "count", "totalValue", "averageValue", "averageDaysInStage" ], "additionalProperties": false } } }, "required": [ "totalOpportunities", "totalValue", "avgDealSize", "avgTimeToClose", "winRate", "lossRate", "activeOpportunities", "closedWonOpportunities", "closedLostOpportunities", "pipelineValue", "stageDistribution" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities/{opportunityId}": { "get": { "operationId": "opportunity.get", "summary": "Get an opportunity", "description": "Reads one opportunity by id, with its description, value, timeline and the quotes raised against it. An id belonging to another tenant, to a hidden client, or to an opportunity the PSA no longer backs answers not_found; existence is never leaked.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "stage": { "type": "string" }, "stageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "estimatedValue": { "type": "number" }, "closeDate": { "type": [ "string", "null" ] }, "clientName": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "quotes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "totalAmount": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "totalAmount", "createdAt" ], "additionalProperties": false } }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "stage", "stageId", "estimatedValue", "closeDate", "clientName", "clientId", "clientUrl", "createdAt", "description", "quotes", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "opportunity.update", "summary": "Update an opportunity", "description": "Updates an existing opportunity. stageId takes priority over stage (a name, matched case-insensitively). Sending status won or lost selects the workspace's matching closed stage and leaves the opportunity's status field unchanged. value sets the total and the services forecast together and cannot be combined with forecastedValueServices. null clears the description, notes, source, business unit, decision criteria, timeline notes, tags, close date, site or a contact. Moving the opportunity to another client clears its site unless a site of the new client is given, and is refused with conflict for an opportunity ConnectWise holds, which is moved in ConnectWise. An opportunity id outside the tenant, on an archived client, or that does not exist answers not_found, as does a client, contact or site id outside the tenant or a site that is not the client's; giving no field to change answers validation_failed. customFields can only be set from a signed-in session. A stage change starts the workspace's stage-changed workflows, and a change to the name, close date, contact, site, probability or description of an opportunity ConnectWise holds is queued for ConnectWise; connectwiseWriteBack says what was queued and which fields ConnectWise could not take. record is the full opportunity for a signed-in caller and null for an API key.", "tags": [ "opportunity" ], "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "value": { "type": "number", "minimum": 0 }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stage": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "archived", "deleted", "open", "won", "lost" ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "forecastedValueServices": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "forecastedValueProducts": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "forecastedValueRecurring": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "businessUnit": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "decisionCriteria": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "timelineNotes": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "tags": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Update an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "stage": { "type": "string" }, "stageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "estimatedValue": { "type": "number" }, "closeDate": { "type": [ "string", "null" ] }, "clientName": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "stage", "stageId", "estimatedValue", "closeDate", "clientName", "clientId", "clientUrl", "createdAt" ], "additionalProperties": false }, "record": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "tenantName": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "opportunityTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedQuoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "probability": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "actualCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "forecastedValueServices": { "type": [ "number", "null" ] }, "forecastedValueProducts": { "type": [ "number", "null" ] }, "forecastedValueRecurring": { "type": [ "number", "null" ] }, "forecastedTcv": { "type": [ "number", "null" ] }, "forecastedMrr": { "type": [ "number", "null" ] }, "forecastedArr": { "type": [ "number", "null" ] }, "wonValueServices": { "type": [ "number", "null" ] }, "wonValueProducts": { "type": [ "number", "null" ] }, "wonValueRecurring": { "type": [ "number", "null" ] }, "wonTcv": { "type": [ "number", "null" ] }, "wonMrr": { "type": [ "number", "null" ] }, "wonArr": { "type": [ "number", "null" ] }, "lostValueServices": { "type": [ "number", "null" ] }, "lostValueProducts": { "type": [ "number", "null" ] }, "lostValueRecurring": { "type": [ "number", "null" ] }, "lostTcv": { "type": [ "number", "null" ] }, "lostMrr": { "type": [ "number", "null" ] }, "lostArr": { "type": [ "number", "null" ] }, "businessUnit": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "decisionCriteria": { "type": [ "string", "null" ] }, "timelineNotes": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "primarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "primarySalesRepName": { "type": [ "string", "null" ] }, "secondarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "secondarySalesRepName": { "type": [ "string", "null" ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackError": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "opportunityType": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "stageOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isClosedWon": { "type": [ "boolean", "null" ] }, "isClosedLost": { "type": [ "boolean", "null" ] }, "isArchived": { "type": [ "boolean", "null" ] }, "archivedReason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sourceIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "name", "description", "stageOrder", "color", "icon", "isDefault", "isClosedWon", "isClosedLost", "isArchived", "archivedReason", "source", "sourceIntegrationId", "createdAt", "updatedAt" ], "additionalProperties": false }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "connectwiseAccountId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "logoUrl", "connectwiseAccountId" ], "additionalProperties": false }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "billingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "shippingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "clientId", "addressLine1", "addressLine2", "city", "state", "zip", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "title", "description", "status", "clientId", "clientName", "tenantName", "contactId", "billingContactId", "shippingContactId", "siteId", "stageId", "ownerId", "opportunityTypeId", "linkedQuoteId", "probability", "expectedCloseDate", "actualCloseDate", "forecastedValueServices", "forecastedValueProducts", "forecastedValueRecurring", "forecastedTcv", "forecastedMrr", "forecastedArr", "wonValueServices", "wonValueProducts", "wonValueRecurring", "wonTcv", "wonMrr", "wonArr", "lostValueServices", "lostValueProducts", "lostValueRecurring", "lostTcv", "lostMrr", "lostArr", "businessUnit", "source", "decisionCriteria", "timelineNotes", "notes", "tags", "customFields", "primarySalesRepId", "primarySalesRepName", "secondarySalesRepId", "secondarySalesRepName", "connectwiseOpportunityId", "haloOpportunityId", "connectwiseSyncStatus", "connectwiseWritebackStatus", "connectwiseWritebackError", "createdBy", "updatedBy", "createdAt", "updatedAt", "opportunityType", "stage", "client", "owner", "contact", "billingContact", "shippingContact", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "connectwiseWriteBack": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "already_queued", "nothing_to_send", "client_not_linked", "opportunity_not_linked", "not_connected", "refused" ] }, "skippedFields": { "type": "array", "items": { "type": "string" } }, "reason": { "type": [ "string", "null" ] } }, "required": [ "status", "skippedFields", "reason" ], "additionalProperties": false } }, "required": [ "opportunity", "record", "connectwiseWriteBack" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/opportunities": { "post": { "operationId": "opportunity.create", "summary": "Create an opportunity", "description": "Creates a new opportunity for a client in the caller's tenant, always at status active, owned by the signed-in caller. stageId takes priority over stage (a name, matched case-insensitively); with neither, the workspace's default pipeline stage is used, or its first stage when no default is set. A stageId that is not one of the workspace's active stages answers conflict and creates nothing. value sets the total and the services forecast together; the three forecastedValue fields set the services, products and recurring forecasts on their own, and value cannot be combined with forecastedValueServices. A client id outside the tenant, archived, or that does not exist answers not_found, as does a contactId that does not belong to the given client, a siteId that is not an active site of that client, and a billing or shipping contact outside the tenant. customFields can only be set from a signed-in session. Creating an opportunity starts the workspace's opportunity-created workflows and, when the client is linked to ConnectWise, queues the opportunity for ConnectWise; connectwiseWriteBack says what was queued, and names a refusal when ConnectWise would reject the opportunity for lacking a sales rep or a synced contact. record is the full opportunity for a signed-in caller and null for an API key.", "tags": [ "opportunity" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1 }, "value": { "type": "number", "minimum": 0 }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stage": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "contactId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "siteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "billingContactId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "shippingContactId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "forecastedValueServices": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "forecastedValueProducts": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "forecastedValueRecurring": { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, "expectedCloseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "businessUnit": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "decisionCriteria": { "type": "string", "minLength": 1 }, "timelineNotes": { "type": "string", "minLength": 1 }, "notes": { "type": "string", "minLength": 1 }, "tags": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "customFields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "clientId", "name" ] } } } }, "responses": { "200": { "description": "Create an opportunity", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "stage": { "type": "string" }, "stageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "estimatedValue": { "type": "number" }, "closeDate": { "type": [ "string", "null" ] }, "clientName": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "status", "stage", "stageId", "estimatedValue", "closeDate", "clientName", "clientId", "clientUrl", "createdAt" ], "additionalProperties": false }, "record": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "tenantName": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingContactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "opportunityTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "linkedQuoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "probability": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "actualCloseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "forecastedValueServices": { "type": [ "number", "null" ] }, "forecastedValueProducts": { "type": [ "number", "null" ] }, "forecastedValueRecurring": { "type": [ "number", "null" ] }, "forecastedTcv": { "type": [ "number", "null" ] }, "forecastedMrr": { "type": [ "number", "null" ] }, "forecastedArr": { "type": [ "number", "null" ] }, "wonValueServices": { "type": [ "number", "null" ] }, "wonValueProducts": { "type": [ "number", "null" ] }, "wonValueRecurring": { "type": [ "number", "null" ] }, "wonTcv": { "type": [ "number", "null" ] }, "wonMrr": { "type": [ "number", "null" ] }, "wonArr": { "type": [ "number", "null" ] }, "lostValueServices": { "type": [ "number", "null" ] }, "lostValueProducts": { "type": [ "number", "null" ] }, "lostValueRecurring": { "type": [ "number", "null" ] }, "lostTcv": { "type": [ "number", "null" ] }, "lostMrr": { "type": [ "number", "null" ] }, "lostArr": { "type": [ "number", "null" ] }, "businessUnit": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "decisionCriteria": { "type": [ "string", "null" ] }, "timelineNotes": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "primarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "primarySalesRepName": { "type": [ "string", "null" ] }, "secondarySalesRepId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "secondarySalesRepName": { "type": [ "string", "null" ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "haloOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connectwiseSyncStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackStatus": { "type": [ "string", "null" ] }, "connectwiseWritebackError": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "opportunityType": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "stageOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isClosedWon": { "type": [ "boolean", "null" ] }, "isClosedLost": { "type": [ "boolean", "null" ] }, "isArchived": { "type": [ "boolean", "null" ] }, "archivedReason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sourceIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "name", "description", "stageOrder", "color", "icon", "isDefault", "isClosedWon", "isClosedLost", "isArchived", "archivedReason", "source", "sourceIntegrationId", "createdAt", "updatedAt" ], "additionalProperties": false }, "client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "connectwiseAccountId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "logoUrl", "connectwiseAccountId" ], "additionalProperties": false }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "billingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "shippingContact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "clientId", "addressLine1", "addressLine2", "city", "state", "zip", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "title", "description", "status", "clientId", "clientName", "tenantName", "contactId", "billingContactId", "shippingContactId", "siteId", "stageId", "ownerId", "opportunityTypeId", "linkedQuoteId", "probability", "expectedCloseDate", "actualCloseDate", "forecastedValueServices", "forecastedValueProducts", "forecastedValueRecurring", "forecastedTcv", "forecastedMrr", "forecastedArr", "wonValueServices", "wonValueProducts", "wonValueRecurring", "wonTcv", "wonMrr", "wonArr", "lostValueServices", "lostValueProducts", "lostValueRecurring", "lostTcv", "lostMrr", "lostArr", "businessUnit", "source", "decisionCriteria", "timelineNotes", "notes", "tags", "customFields", "primarySalesRepId", "primarySalesRepName", "secondarySalesRepId", "secondarySalesRepName", "connectwiseOpportunityId", "haloOpportunityId", "connectwiseSyncStatus", "connectwiseWritebackStatus", "connectwiseWritebackError", "createdBy", "updatedBy", "createdAt", "updatedAt", "opportunityType", "stage", "client", "owner", "contact", "billingContact", "shippingContact", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "connectwiseWriteBack": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "already_queued", "nothing_to_send", "client_not_linked", "opportunity_not_linked", "not_connected", "refused" ] }, "skippedFields": { "type": "array", "items": { "type": "string" } }, "reason": { "type": [ "string", "null" ] } }, "required": [ "status", "skippedFields", "reason" ], "additionalProperties": false } }, "required": [ "opportunity", "record", "connectwiseWriteBack" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/configurations/search": { "get": { "operationId": "configuration.search", "summary": "Search configurations", "description": "Searches one client's configurations and assets by name, device/serial/tag identifier, type, or status. A client that is hidden answers not_found rather than an empty list, and a configuration every linked source reports as removed is excluded. Ordered by configuration name with the configuration id as tiebreaker and paged with an opaque cursor.", "tags": [ "configuration" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search configurations", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "clientUrl": { "type": "string" }, "deviceIdentifier": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "serialNumber": { "type": [ "string", "null" ] }, "tagNumber": { "type": [ "string", "null" ] }, "siteName": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "modelNumber": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "type", "status", "description", "clientId", "clientName", "clientUrl", "deviceIdentifier", "ipAddress", "serialNumber", "tagNumber", "siteName", "location", "manufacturer", "modelNumber", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/sites": { "get": { "operationId": "site.list", "summary": "List sites", "description": "Pages through the sites in the caller's tenant, optionally narrowed to one client. A site whose client is hidden, one every linked source reports removed, one the sync has orphaned, and one the PSA marks inactive are all excluded. Ordered by id so a cursor is stable while rows are written.", "tags": [ "site" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "List sites", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "isInactive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "addressLine1", "addressLine2", "city", "state", "zip", "country", "phone", "timeZone", "isDefault", "isInactive", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "site.create", "summary": "Create a site", "description": "Creates a new site (physical location) under a client in the caller's tenant. isDefault is caller-specified; no site is auto-promoted to default on create. A client id outside the tenant, archived, or that does not exist answers not_found.", "tags": [ "site" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1 }, "addressLine1": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "clientId", "name" ] } } } }, "responses": { "200": { "description": "Create a site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "isInactive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "addressLine1", "addressLine2", "city", "state", "zip", "country", "phone", "timeZone", "isDefault", "isInactive", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "site" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/sites/{siteId}": { "get": { "operationId": "site.get", "summary": "Get a site", "description": "Reads one active site in the caller's tenant. An archived site, one the PSA marks inactive, one every linked source reports removed, one the sync has orphaned, one under a hidden client, and one in another tenant all answer not_found.", "tags": [ "site" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "isInactive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "addressLine1", "addressLine2", "city", "state", "zip", "country", "phone", "timeZone", "isDefault", "isInactive", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "site" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "site.update", "summary": "Update a site", "description": "Updates one or more fields of an existing site in the caller's tenant. A field left out of the request is unchanged; a field sent as null clears it. clientId can reparent a manual site to a different client in the same tenant. For a site with active ConnectWise provenance, changing clientId or country answers conflict and writes nothing because neither has supported write-back. Other changed fields require enabled write-back, values ConnectWise accepts and a successfully queued provider command, or the whole update answers conflict and writes nothing. Unchanged values are allowed without a new provider command. crmWriteBackEnqueued reports whether this update queued a command. A site id outside the tenant or that does not exist answers not_found; a client id outside the tenant, archived, or that does not exist answers not_found.", "tags": [ "site" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1 }, "addressLine1": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Update a site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "isInactive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "addressLine1", "addressLine2", "city", "state", "zip", "country", "phone", "timeZone", "isDefault", "isInactive", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "crmWriteBackEnqueued": { "type": "boolean" } }, "required": [ "site", "crmWriteBackEnqueued" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "delete": { "operationId": "location.delete", "summary": "Delete a site", "description": "Permanently deletes a site (physical location) in the caller's workspace. Related agreements, clients, configurations, contacts, opportunities, quotes and tickets are kept, but their references to the deleted site are cleared. A client's default site and quote shipping locations are also cleared when they name this site. Deletes the site in Scopable only; a ConnectWise site of the same name is untouched. A site id outside the workspace, or that does not exist, answers not_found.", "tags": [ "location" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Delete a site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "siteId" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/sites/{siteId}/archive": { "post": { "operationId": "site.archive", "summary": "Archive a site", "description": "Soft-deletes one site in the caller's tenant: hides it from every site read, clears its default flag, and clears the client's default-site pointer if this site held it. The record and every reference to it are kept. Archiving is Scopable-only and is not written back to ConnectWise or Halo, and no sync reverses it. A site that is already archived answers with its current state rather than an error. A site id outside the tenant or that does not exist answers not_found.", "tags": [ "site" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Archive a site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "isInactive": { "type": "boolean" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "addressLine1", "addressLine2", "city", "state", "zip", "country", "phone", "timeZone", "isDefault", "isInactive", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "archivedAt": { "type": "string" }, "defaultSiteCleared": { "type": "boolean" } }, "required": [ "site", "archivedAt", "defaultSiteCleared" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/agreements": { "get": { "operationId": "agreement.search", "summary": "Search agreements", "description": "Pages through the caller's tenant's agreements, filtered by client, free text over the agreement name, and status. An agreement whose client is hidden, one a resync has orphaned, and one the PSA no longer backs are excluded. Ordered by id so a cursor is stable while rows are written.", "tags": [ "agreement" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "Search agreements", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "billingCycle": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "renewalDate": { "type": [ "string", "null" ] }, "autoRenewal": { "type": [ "boolean", "null" ] }, "currency": { "type": [ "string", "null" ] }, "amountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overageRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedHours": { "type": [ "number", "null" ] }, "hoursUsed": { "type": [ "number", "null" ] }, "hoursRemaining": { "type": [ "number", "null" ] }, "cancelledFlag": { "type": [ "boolean", "null" ] }, "expiredFlag": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ] }, "billingTermsText": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "billAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAdditionsAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "noEndingDateFlag": { "type": [ "boolean", "null" ] }, "billingMethod": { "type": [ "string", "null" ] }, "sla": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "coverageType": { "type": [ "string", "null" ] }, "customerPo": { "type": [ "string", "null" ] }, "workOrder": { "type": [ "string", "null" ] }, "invoiceDescription": { "type": [ "string", "null" ] }, "invoiceTemplate": { "type": [ "string", "null" ] }, "internalNotes": { "type": [ "string", "null" ] } }, "required": [ "id", "clientId", "clientName", "name", "type", "status", "billingCycle", "startDate", "endDate", "renewalDate", "autoRenewal", "currency", "amountMinor", "hourlyRateMinor", "overageRateMinor", "includedHours", "hoursUsed", "hoursRemaining", "cancelledFlag", "expiredFlag", "notes", "billingTermsText", "source", "lastSyncedAt", "createdAt", "updatedAt", "billAmountMinor", "totalAdditionsAmountMinor", "noEndingDateFlag", "billingMethod", "sla", "location", "department", "coverageType", "customerPo", "workOrder", "invoiceDescription", "invoiceTemplate", "internalNotes" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/agreements/sync-readiness": { "get": { "operationId": "agreement.sync_readiness", "summary": "Get the agreement sync status", "description": "Whether the caller's tenant has any agreements synced from the PSA, and the latest ConnectWise agreement sync: the one running now, otherwise the last one to finish. Agreements sync by hand today, so there is no schedule.", "tags": [ "agreement" ], "parameters": [], "responses": { "200": { "description": "Get the agreement sync status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "syncMode": { "type": "string", "const": "manual" }, "schedule": { "type": "string", "const": "not_scheduled" }, "hasSyncedAgreements": { "type": "boolean" }, "emptyStateReason": { "type": "string", "enum": [ "manual_sync_required", "sync_failed", "sync_in_progress" ] }, "latestAgreementSync": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" }, "recordsProcessed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recordsErrored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastError": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "startedAt", "completedAt", "updatedAt", "recordsProcessed", "recordsErrored", "lastError" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "syncMode", "schedule", "hasSyncedAgreements", "emptyStateReason", "latestAgreementSync" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/agreements/analytics": { "get": { "operationId": "agreement.analytics", "summary": "Get agreement analytics", "description": "A roll-up of the caller's tenant's agreements: active count, monthly and annual recurring revenue, the split by agreement type, agreements expiring within 30 days or expired, agreements with no recurring amount, and how many visible clients have or lack an active agreement. Counts only agreements and clients the Agreements list shows. Fails rather than reporting zero clients when the client count cannot be read.", "tags": [ "agreement" ], "parameters": [], "responses": { "200": { "description": "Get agreement analytics", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ] }, "totalActive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalMrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalArrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "byType": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type", "count", "mrrMinor" ], "additionalProperties": false } }, "expiringSoon": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expired": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "zeroAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clientCoverage": { "type": "object", "properties": { "withAgreements": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "withoutAgreements": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgPerClient": { "type": "number" } }, "required": [ "withAgreements", "withoutAgreements", "avgPerClient" ], "additionalProperties": false } }, "required": [ "currency", "totalActive", "totalMrrMinor", "totalArrMinor", "byType", "expiringSoon", "expired", "zeroAmount", "clientCoverage" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/agreements/{agreementId}": { "get": { "operationId": "agreement.get", "summary": "Get an agreement", "description": "Reads one agreement by id from the caller's tenant, with its client's name, its start, end, renewal, and auto-renewal terms, and its billing and invoicing details. An id belonging to another tenant, to a hidden client, or to an agreement the PSA no longer backs answers not_found alike; existence is never leaked.", "tags": [ "agreement" ], "parameters": [ { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get an agreement", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": "string" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "billingCycle": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "renewalDate": { "type": [ "string", "null" ] }, "autoRenewal": { "type": [ "boolean", "null" ] }, "currency": { "type": [ "string", "null" ] }, "amountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overageRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "includedHours": { "type": [ "number", "null" ] }, "hoursUsed": { "type": [ "number", "null" ] }, "hoursRemaining": { "type": [ "number", "null" ] }, "cancelledFlag": { "type": [ "boolean", "null" ] }, "expiredFlag": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ] }, "billingTermsText": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "billAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAdditionsAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "noEndingDateFlag": { "type": [ "boolean", "null" ] }, "billingMethod": { "type": [ "string", "null" ] }, "sla": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "coverageType": { "type": [ "string", "null" ] }, "customerPo": { "type": [ "string", "null" ] }, "workOrder": { "type": [ "string", "null" ] }, "invoiceDescription": { "type": [ "string", "null" ] }, "invoiceTemplate": { "type": [ "string", "null" ] }, "internalNotes": { "type": [ "string", "null" ] } }, "required": [ "id", "clientId", "clientName", "name", "type", "status", "billingCycle", "startDate", "endDate", "renewalDate", "autoRenewal", "currency", "amountMinor", "hourlyRateMinor", "overageRateMinor", "includedHours", "hoursUsed", "hoursRemaining", "cancelledFlag", "expiredFlag", "notes", "billingTermsText", "source", "lastSyncedAt", "createdAt", "updatedAt", "billAmountMinor", "totalAdditionsAmountMinor", "noEndingDateFlag", "billingMethod", "sla", "location", "department", "coverageType", "customerPo", "workOrder", "invoiceDescription", "invoiceTemplate", "internalNotes" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/tickets/search": { "get": { "operationId": "ticket.search", "summary": "Search tickets", "description": "Pages through the caller's tenant's tickets, filtered by client, free text over the summary, record type, and open or closed. A ticket whose client is hidden and one the PSA no longer backs are excluded; a ticket that names no client is returned, because it belongs to the tenant rather than to a company. Ordered by id so a cursor is stable while rows are written.", "tags": [ "ticket" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "recordType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ServiceTicket", "ProjectTicket", "ProjectIssue" ] } }, { "name": "open", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Search tickets", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "agreementId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "recordType": { "anyOf": [ { "type": "string", "enum": [ "ServiceTicket", "ProjectTicket", "ProjectIssue" ] }, { "type": "null" } ] }, "summary": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "board": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "dateEntered": { "type": [ "string", "null" ] }, "requiredDate": { "type": [ "string", "null" ] }, "dateResolved": { "type": [ "string", "null" ] }, "closedDate": { "type": [ "string", "null" ] }, "closedFlag": { "type": "boolean" }, "isInSla": { "type": [ "boolean", "null" ] }, "slaStatus": { "type": [ "string", "null" ] }, "respondMinutes": { "type": [ "number", "null" ] }, "resolveMinutes": { "type": [ "number", "null" ] }, "actualHours": { "type": [ "number", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "siteId", "contactId", "agreementId", "recordType", "summary", "status", "priority", "board", "ownerName", "dateEntered", "requiredDate", "dateResolved", "closedDate", "closedFlag", "isInSla", "slaStatus", "respondMinutes", "resolveMinutes", "actualHours", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/tickets/time-breakdown": { "get": { "operationId": "ticket.time_breakdown", "summary": "Get a deterministic labor-hours breakdown for a set of tickets", "description": "Reads the labor hours logged against up to 100 tickets in the caller's tenant, given as one comma-separated string of ticket ids, grouped by work type, with entry and ticket counts per group and a grand total. A ticket whose client is hidden or that the PSA no longer backs contributes nothing, the same visibility rule ticket.get and ticket.search apply. noData is true when none of the given tickets have a single time entry -- distinct from a real zero, which a caller must not confuse with missing data.", "tags": [ "ticket" ], "parameters": [ { "name": "ticketIds", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Comma-separated ticket ids (UUIDs) in one string, at most 100. Not an array." } } ], "responses": { "200": { "description": "Get a deterministic labor-hours breakdown for a set of tickets", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "breakdown": { "type": "array", "items": { "type": "object", "properties": { "workTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workTypeName": { "type": "string" }, "totalHours": { "type": [ "number", "null" ] }, "billedHours": { "type": "number" }, "entryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ticketCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workTypeId", "workTypeName", "totalHours", "billedHours", "entryCount", "ticketCount" ], "additionalProperties": false } }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "grandTotalHours": { "type": [ "number", "null" ] }, "noData": { "type": "boolean" } }, "required": [ "breakdown", "count", "grandTotalHours", "noData" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/tickets/concept-search": { "get": { "operationId": "ticket.concept_search", "summary": "Find past tickets for a kind of work", "description": "Finds the caller's tenant's tickets that look like a kind of work, for example a firewall replacement, closest match first, optionally for one client and an entered-date window. The results are candidates: judge which genuinely match, then call ticket.time_breakdown on the ones you keep for the hours actually logged. A ticket whose client is hidden or that the PSA no longer backs is never returned. Returns at most limit rows (default 25, at most 100), not a cursor-paged list. retrieval says whether the search ranked by meaning and keywords or by keywords alone, and why.", "tags": [ "ticket" ], "parameters": [ { "name": "concept", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Find past tickets for a kind of work", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "summary": { "type": [ "string", "null" ] }, "typeName": { "type": [ "string", "null" ] }, "subtypeName": { "type": [ "string", "null" ] }, "dateEntered": { "type": [ "string", "null" ] }, "closedDate": { "type": [ "string", "null" ] }, "actualHours": { "type": [ "number", "null" ] }, "relevanceScore": { "type": "number" } }, "required": [ "id", "summary", "typeName", "subtypeName", "dateEntered", "closedDate", "actualHours", "relevanceScore" ], "additionalProperties": false } }, "retrieval": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "hybrid", "keyword" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "embeddings_not_configured", "embeddings_failed" ] }, { "type": "null" } ] } }, "required": [ "mode", "reason" ], "additionalProperties": false } }, "required": [ "data", "retrieval" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/tickets/{ticketId}": { "get": { "operationId": "ticket.get", "summary": "Get a ticket", "description": "Reads one ticket by id from the caller's tenant, with its note history, the time charged to it, and its sentiment reading. Notes the PSA marks internal or internal-analysis are never returned, and a time entry's free-text notes are not served at all. Both collections carry the 100 most recent rows, oldest first, and truncated says whether that cap was reached. An id belonging to another tenant, to a hidden client, or to a ticket the PSA no longer backs answers not_found alike; existence is never leaked.", "tags": [ "ticket" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a ticket", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "agreementId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "recordType": { "anyOf": [ { "type": "string", "enum": [ "ServiceTicket", "ProjectTicket", "ProjectIssue" ] }, { "type": "null" } ] }, "summary": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "board": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "dateEntered": { "type": [ "string", "null" ] }, "requiredDate": { "type": [ "string", "null" ] }, "dateResolved": { "type": [ "string", "null" ] }, "closedDate": { "type": [ "string", "null" ] }, "closedFlag": { "type": "boolean" }, "isInSla": { "type": [ "boolean", "null" ] }, "slaStatus": { "type": [ "string", "null" ] }, "respondMinutes": { "type": [ "number", "null" ] }, "resolveMinutes": { "type": [ "number", "null" ] }, "actualHours": { "type": [ "number", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "text": { "type": [ "string", "null" ] }, "authorName": { "type": [ "string", "null" ] }, "detailDescriptionFlag": { "type": "boolean" }, "resolutionFlag": { "type": "boolean" }, "externalFlag": { "type": "boolean" }, "customerUpdatedFlag": { "type": "boolean" }, "sentimentScore": { "type": [ "number", "null" ] }, "dateCreated": { "type": [ "string", "null" ] } }, "required": [ "id", "text", "authorName", "detailDescriptionFlag", "resolutionFlag", "externalFlag", "customerUpdatedFlag", "sentimentScore", "dateCreated" ], "additionalProperties": false } }, "timeEntries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "memberName": { "type": [ "string", "null" ] }, "actualHours": { "type": [ "number", "null" ] }, "hoursBilled": { "type": [ "number", "null" ] }, "billableOption": { "type": [ "string", "null" ] }, "timeStart": { "type": [ "string", "null" ] }, "timeEnd": { "type": [ "string", "null" ] }, "dateEntered": { "type": [ "string", "null" ] } }, "required": [ "id", "memberName", "actualHours", "hoursBilled", "billableOption", "timeStart", "timeEnd", "dateEntered" ], "additionalProperties": false } }, "truncated": { "type": "object", "properties": { "notes": { "type": "boolean" }, "timeEntries": { "type": "boolean" } }, "required": [ "notes", "timeEntries" ], "additionalProperties": false }, "sentiment": { "anyOf": [ { "type": "object", "properties": { "sentimentScore": { "type": "number" }, "sentimentLabel": { "type": "string" }, "trajectory": { "type": "string" }, "themes": { "type": "array", "items": { "type": "string" } }, "riskFlags": { "type": "array", "items": { "type": "string" } }, "analyzedAt": { "type": "string" } }, "required": [ "sentimentScore", "sentimentLabel", "trajectory", "themes", "riskFlags", "analyzedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "clientId", "siteId", "contactId", "agreementId", "recordType", "summary", "status", "priority", "board", "ownerName", "dateEntered", "requiredDate", "dateResolved", "closedDate", "closedFlag", "isInSla", "slaStatus", "respondMinutes", "resolveMinutes", "actualHours", "createdAt", "updatedAt", "notes", "timeEntries", "truncated", "sentiment" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/projects": { "get": { "operationId": "project.list", "summary": "List projects", "description": "Pages through the caller's tenant's project tickets, filtered by client and free text over the name. Excludes projects whose client is hidden and projects no longer present in the PSA. Ordered by id and paged with an opaque cursor.", "tags": [ "project" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "List projects", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "board": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "string", "null" ] }, "targetDate": { "type": [ "string", "null" ] }, "resolvedAt": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "closedFlag": { "type": "boolean" }, "actualHours": { "type": [ "number", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "clientId", "name", "status", "priority", "board", "ownerName", "openedAt", "targetDate", "resolvedAt", "closedAt", "closedFlag", "actualHours", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/clients/{clientId}/service-health": { "get": { "operationId": "service_health.get", "summary": "Get a client's service health", "description": "Reads a client's service health: a live sentiment and risk-flag rollup computed from analyzed tickets over a trailing window, plus the most recent narrative the app has cached for the client that has not expired. The narrative may describe a different window from the rollup, which its own windowStart and windowEnd state; it is null when nothing unexpired is cached, and this operation never generates one. A client id belonging to another tenant, or to a client the app hides, answers not_found alike; existence is never leaked.", "tags": [ "service_health" ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "windowDays", "in": "query", "required": false, "schema": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Get a client's service health", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "windowStart": { "type": "string" }, "windowEnd": { "type": "string" }, "narrative": { "anyOf": [ { "type": "object", "properties": { "headline": { "type": "string" }, "narrative": { "type": "string" }, "recommendedFocus": { "type": "array", "items": { "type": "string" } }, "ticketCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "windowStart": { "type": "string" }, "windowEnd": { "type": "string" }, "generatedAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "headline", "narrative", "recommendedFocus", "ticketCount", "windowStart", "windowEnd", "generatedAt", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "rollup": { "type": "object", "properties": { "ticketCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "averageSentimentScore": { "type": [ "number", "null" ] }, "sentimentLabelCounts": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mixed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative", "mixed" ], "additionalProperties": false }, "riskFlagCounts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "latestSentimentScore": { "type": [ "number", "null" ] }, "latestSentimentLabel": { "type": [ "string", "null" ] }, "latestTrajectory": { "type": [ "string", "null" ] }, "trend": { "type": "array", "items": { "type": "object", "properties": { "ticketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "dateEntered": { "type": [ "string", "null" ] }, "windowDate": { "type": "string" }, "analyzedAt": { "type": "string" }, "sentimentScore": { "type": "number" }, "sentimentLabel": { "type": "string" }, "trajectory": { "type": "string" }, "riskFlags": { "type": "array", "items": { "type": "string" } } }, "required": [ "ticketId", "dateEntered", "windowDate", "analyzedAt", "sentimentScore", "sentimentLabel", "trajectory", "riskFlags" ], "additionalProperties": false } }, "trendTruncated": { "type": "boolean" } }, "required": [ "ticketCount", "averageSentimentScore", "sentimentLabelCounts", "riskFlagCounts", "latestSentimentScore", "latestSentimentLabel", "latestTrajectory", "trend", "trendTruncated" ], "additionalProperties": false }, "freshness": { "type": "object", "properties": { "narrativeGeneratedAt": { "type": [ "string", "null" ] }, "rollupComputedAt": { "type": "string" } }, "required": [ "narrativeGeneratedAt", "rollupComputedAt" ], "additionalProperties": false } }, "required": [ "clientId", "windowStart", "windowEnd", "narrative", "rollup", "freshness" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/dashboard/stats": { "get": { "operationId": "dashboard.get_stats", "summary": "Get the tenant's dashboard stats snapshot", "description": "A snapshot of the caller's tenant's quote and opportunity pipeline: totals, win rates, MRR/NRR, and deal-size averages. Excludes a client whose only source reports it removed from the active-client count; every other total and rate is a plain aggregate over the tenant's quotes and opportunities.", "tags": [ "dashboard" ], "parameters": [], "responses": { "200": { "description": "Get the tenant's dashboard stats snapshot", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ] }, "totalQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalValueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pendingQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "winRatePercentage": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "activeClients": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pendingMrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pendingNrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "wonRevenueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "wonMrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "wonNrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "wonQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lostQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "draftQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgDealSizeMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pipelineValueSentMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quoteToCloseRatio": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "activeOpportunities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oppPipelineValueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "weightedPipelineValueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closedWonOpps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oppWinRate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgOppDealSizeMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "currency", "totalQuotes", "totalValueMinor", "pendingQuotes", "winRatePercentage", "activeClients", "pendingMrrMinor", "pendingNrrMinor", "wonRevenueMinor", "wonMrrMinor", "wonNrrMinor", "wonQuotes", "lostQuotes", "draftQuotes", "avgDealSizeMinor", "pipelineValueSentMinor", "quoteToCloseRatio", "activeOpportunities", "oppPipelineValueMinor", "weightedPipelineValueMinor", "closedWonOpps", "oppWinRate", "avgOppDealSizeMinor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/dashboard/metrics": { "get": { "operationId": "dashboard.get_metrics", "summary": "Get the tenant's dashboard chart metrics", "description": "The caller's tenant's quote pipeline broken into chart-ready buckets: won quotes and won MRR/NRR over trailing 30/60/90-day windows, quote counts for the last 6 months, projected MRR/NRR for the next 6 months, and the overall close rate.", "tags": [ "dashboard" ], "parameters": [], "responses": { "200": { "description": "Get the tenant's dashboard chart metrics", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ] }, "openQuotes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "wonQuotes": { "type": "object", "properties": { "days30": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days60": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days90": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "days30", "days60", "days90" ], "additionalProperties": false }, "wonMrr": { "type": "object", "properties": { "days30Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days60Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days90Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "days30Minor", "days60Minor", "days90Minor" ], "additionalProperties": false }, "wonNrr": { "type": "object", "properties": { "days30Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days60Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days90Minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "days30Minor", "days60Minor", "days90Minor" ], "additionalProperties": false }, "quotesByMonth": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "month", "count" ], "additionalProperties": false } }, "pipelineMrr": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "valueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "month", "valueMinor" ], "additionalProperties": false } }, "pipelineNrr": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "valueMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "month", "valueMinor" ], "additionalProperties": false } }, "closeRate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closeRateWon": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closeRateLost": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "currency", "openQuotes", "wonQuotes", "wonMrr", "wonNrr", "quotesByMonth", "pipelineMrr", "pipelineNrr", "closeRate", "closeRateWon", "closeRateLost" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/products/search": { "get": { "operationId": "product.search", "summary": "Search the product catalog", "description": "Searches the workspace's managed product catalog by name, SKU, manufacturer, or ConnectWise product id, optionally narrowed by category and vendor. Inactive products and products a linked PSA reports as removed are excluded. Results are ordered by description with the product id as tiebreaker and paged with an opaque cursor. This is product identity and the MSP's own catalog pricing, not live distributor cost or availability: distributor.catalog_search searches the connected distributors' live catalogs.", "tags": [ "product" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "vendor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Search the product catalog", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "unitPrice": { "type": [ "number", "null" ] }, "unitCost": { "type": [ "number", "null" ] }, "productClass": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "billingCycle": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "product_catalog" } }, "required": [ "id", "sku", "name", "description", "unitPrice", "unitCost", "productClass", "manufacturer", "vendor", "category", "isRecurring", "billingCycle", "source" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/distributors/catalog/search": { "get": { "operationId": "distributor.catalog_search", "summary": "Search connected distributor catalogs", "description": "Searches the live catalogs of the distributors this workspace has connected (Ingram Micro, Pax8, and TD SYNNEX for a person inside its rollout) for a keyword and returns their first page of matches, up to ten per distributor, with the distributor's cost and suggested retail price where the distributor returns them. Ingram Micro prices come from its live price and availability check on the matched SKUs; a match Ingram Micro could not price comes back with a null cost rather than being dropped. This is not the workspace's own product catalog: use product.search for that, and prefer the catalog row when a SKU appears in both. Every connected distributor is listed in sources with whether it was searched; a distributor that could not be searched is reported with a reason instead of failing the call. A connected CDW is reported unavailable, and a connected TD SYNNEX is left out for anyone outside its rollout. No distributor connected answers with no rows and no sources.", "tags": [ "distributor" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "vendor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Search connected distributor catalogs", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "ingram", "pax8", "cdw", "tdsynnex" ] }, "sourceProductId": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "unitCost": { "type": [ "number", "null" ] }, "retailPrice": { "type": [ "number", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "billingCycle": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "sourceProductId", "sku", "name", "manufacturer", "vendor", "unitCost", "retailPrice", "isRecurring", "billingCycle" ], "additionalProperties": false } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "ingram", "pax8", "cdw", "tdsynnex" ] }, "status": { "type": "string", "enum": [ "searched", "unavailable" ] }, "resultCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "required": [ "source", "status", "resultCount", "reason", "message" ], "additionalProperties": false } } }, "required": [ "data", "sources" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}": { "get": { "operationId": "quote.get", "summary": "Get a quote", "description": "Reads one quote by id with its line items, a pricing summary over them, and its current statement of work. Any quote in the workspace can be read, not only one a conversation is about, so quotes can be compared across clients.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Get a quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "pricingSummary": { "type": "object", "properties": { "totalOneTimeMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "One-time charges, billed once, in minor units." }, "totalMrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monthly recurring revenue in minor units: every recurring line's charge divided by the months in its billing cycle, so a quarterly line counts for a third and an annual line for a twelfth." }, "totalNrrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Non-recurring revenue in minor units. Always equal to totalOneTimeMinor." }, "totalTcvMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total contract value in minor units: the one-time charges plus each recurring line's monthly equivalent over that line's own term. A recurring line with no term of its own counts for twelve months." }, "arrMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Annual recurring revenue in minor units: twelve times totalMrrMinor." }, "monthlyBilledMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the monthly-billed lines charge each month, in minor units." }, "biMonthlyBilledMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the lines billed every two months charge each time, in minor units." }, "quarterlyBilledMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the quarterly-billed lines charge each quarter, in minor units." }, "semiAnnualBilledMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the lines billed every six months charge each time, in minor units." }, "annualBilledMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the annual-billed lines charge each year, in minor units." }, "addOnMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The value over the term of the optional add-on lines that are counted, in minor units. Already included in the totals above." }, "lineItemCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The number of line items on the quote, counted or not." } }, "required": [ "totalOneTimeMinor", "totalMrrMinor", "totalNrrMinor", "totalTcvMinor", "arrMinor", "monthlyBilledMinor", "biMonthlyBilledMinor", "quarterlyBilledMinor", "semiAnnualBilledMinor", "annualBilledMinor", "addOnMinor", "lineItemCount" ], "additionalProperties": false, "description": "Revenue totals over the returned lines, in minor units. On an open quote every line counts except add-ons the client declined, so optional add-ons count until declined. On a won quote only accepted lines count. Each total is summed from unrounded line totals and rounded once, so it can differ by a cent from adding up the lines' rounded extendedPriceMinor values." }, "sow": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "content": { "type": "string" }, "contentFormat": { "type": "string" }, "currentVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sections": {}, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "contentFormat", "currentVersion", "sections", "createdBy", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quote", "lineItems", "pricingSummary", "sow" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "patch": { "operationId": "quote.details_update", "summary": "Update a quote's setup details", "description": "Updates the quote-level fields: title, status, sales stage, probability, value, type, contact, location, dates, reps, client, site, and the linked opportunity. Moving a quote to Sent re-validates it (a client, a title, a positive total, an expiration date that is not past), recalculates the total from the line items, snapshots the client and contact, and records a version. A quote that is Signed, Accepted, or Won is locked: only its status may change. An expectedStatus mismatch refuses the save. Changing or clearing amounts requires quote pricing permission, and a Won status or sales stage requires permission to manually mark quotes won. Fields the linked ConnectWise opportunity mirrors are queued to it; `connectwiseSync` reports which.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "Draft", "Sent", "Published", "Viewed", "Signed", "Accepted", "Declined", "Won", "Lost", "Cancelled", "Expired" ] }, "expectedStatus": { "type": "string", "enum": [ "Draft", "Sent", "Published", "Viewed", "Signed", "Accepted", "Declined", "Won", "Lost", "Cancelled", "Expired" ] }, "salesStage": { "type": "string", "maxLength": 500 }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9999999999, "maximum": 9999999999 }, { "type": "null" } ] }, "quoteType": { "type": "string", "maxLength": 500 }, "contactId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "companyLocation": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "expectedCloseDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "validUntil": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "billingSiteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "shippingSiteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "customerPo": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "wonLossReason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "layoutTemplateId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "salesRep1": { "type": "string", "maxLength": 500 }, "salesRep2": { "type": "string", "maxLength": 500 }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Update a quote's setup details", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "connectwiseSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped_by_policy", "succeeded", "failed", "partial_success" ] }, "attempted": { "type": "boolean" }, "message": { "type": "string" }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "attemptedFields": { "type": "array", "items": { "type": "string" } }, "succeededFields": { "type": "array", "items": { "type": "string" } }, "failedFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "inputField": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "inputField", "message" ], "additionalProperties": false } }, "skippedFields": { "type": "array", "items": { "type": "object", "properties": { "inputField": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "message": { "type": "string" } }, "required": [ "inputField", "field", "reason", "message" ], "additionalProperties": false } } }, "required": [ "status", "attempted", "message", "connectwiseOpportunityId", "attemptedFields", "succeededFields", "failedFields", "skippedFields" ], "additionalProperties": false } }, "required": [ "quote", "lineItems", "connectwiseSync" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes": { "get": { "operationId": "quote.list", "summary": "List quotes", "description": "Pages through the quotes in the caller's tenant, newest first by creation time with the id as tiebreaker, paged with an opaque cursor (default page 50). clientId, salesStage, quoteType, status and salesRep1 narrow the list, and together they all have to hold. A text filter matches the whole value a quote carries in that field, ignoring case, and a quote with no value there never matches. Each row is the quote object quote.get returns, without its line items, pricing summary or statement of work; read one quote for those. Quotes on archived clients are included, as they are for quote.get. A clientId that is not in the caller's tenant matches nothing.", "tags": [ "quote" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "salesStage", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The quote's sales stage, matched whole and ignoring case: Draft, Prospecting, Forecasted, Quoted, Recognized, Signed, Won, Lost or Cancelled." } }, { "name": "quoteType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The quote's type, matched whole and ignoring case, for example Agreement." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The quote's status, matched whole and ignoring case: Draft, Sent, Published, Viewed, Signed, Accepted, Declined, Won, Lost, Cancelled or Expired." } }, { "name": "salesRep1", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The quote's primary sales rep, matched whole and ignoring case." } } ], "responses": { "200": { "description": "List quotes", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "post": { "operationId": "quote.draft_create", "summary": "Create a quote draft", "description": "Creates a Draft quote for a client, with its line items, and sets the site, contact and linked opportunity when they are given. Nothing is sent to the client. With lines, the quote's value is their total; without, it is `valueMinor`. The answer suggests up to three of the client's opportunities whose titles match the quote's, for the caller to decide whether to link one.", "tags": [ "quote" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string", "maxLength": 500 }, "lineItems": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "sku": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0, "maximum": 9999999999 }, "unitCostMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "unitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "category": { "type": "string", "maxLength": 500 }, "billingType": { "type": "string", "enum": [ "one-time", "monthly", "annual" ] }, "description": { "type": "string", "maxLength": 5000 } }, "required": [ "name", "unitPriceMinor" ], "additionalProperties": false } }, "valueMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "salesStage": { "type": "string", "maxLength": 500 }, "quoteType": { "type": "string", "maxLength": 500 }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "salesRep1": { "type": "string", "maxLength": 500 }, "salesRep2": { "type": "string", "maxLength": 500 }, "companyLocation": { "type": "string", "maxLength": 500 }, "contactName": { "type": "string", "maxLength": 500 }, "contactEmail": { "type": "string", "maxLength": 500 }, "contactPhone": { "type": "string", "maxLength": 500 }, "validUntil": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "description": { "type": "string", "maxLength": 10000 }, "opportunityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "siteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "connectwiseOpportunityId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 } }, "required": [ "clientId", "lineItems" ] } } } }, "responses": { "200": { "description": "Create a quote draft", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "opportunityMatchCandidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "matchScore": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "title", "status", "stage", "createdAt", "url", "matchScore" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems", "opportunityMatchCandidates" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/draft-items": { "post": { "operationId": "quote.draft_update", "summary": "Change a quote's line items in one call", "description": "Adds, removes, and updates line items on an existing quote in one save: additions first, then removals, then updates. A line id to remove or update that is not on the quote is refused, and nothing is saved.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "addItems": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "sku": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0, "maximum": 9999999999 }, "unitCostMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "unitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "category": { "type": "string", "maxLength": 500 }, "billingType": { "type": "string", "enum": [ "one-time", "monthly", "annual" ] }, "description": { "type": "string", "maxLength": 5000 } }, "required": [ "name", "unitPriceMinor" ], "additionalProperties": false } }, "removeItems": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "updateItems": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0, "maximum": 9999999999 }, "unitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "unitCostMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "description": { "type": "string", "maxLength": 5000 }, "sku": { "type": "string", "maxLength": 500 }, "category": { "type": "string", "maxLength": 500 }, "billingType": { "type": "string", "enum": [ "one-time", "monthly", "annual" ] } }, "required": [ "lineItemId" ], "additionalProperties": false } } } } } } }, "responses": { "200": { "description": "Change a quote's line items in one call", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/client": { "post": { "operationId": "quote.client_set", "summary": "Set a quote's client", "description": "Points the quote at a different client and clears what belonged to the old one: the contact, the location, the site, and the billing, shipping and per-line Ship To sites.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "clientId" ] } } } }, "responses": { "200": { "description": "Set a quote's client", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "connectwiseSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped_by_policy", "succeeded", "failed", "partial_success" ] }, "attempted": { "type": "boolean" }, "message": { "type": "string" }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "attemptedFields": { "type": "array", "items": { "type": "string" } }, "succeededFields": { "type": "array", "items": { "type": "string" } }, "failedFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "inputField": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "inputField", "message" ], "additionalProperties": false } }, "skippedFields": { "type": "array", "items": { "type": "object", "properties": { "inputField": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "message": { "type": "string" } }, "required": [ "inputField", "field", "reason", "message" ], "additionalProperties": false } } }, "required": [ "status", "attempted", "message", "connectwiseOpportunityId", "attemptedFields", "succeededFields", "failedFields", "skippedFields" ], "additionalProperties": false } }, "required": [ "quote", "lineItems", "connectwiseSync" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/site": { "post": { "operationId": "quote.site_set", "summary": "Set a quote's site", "description": "Selects one of the quote client's sites as the quote's location, and its name as the location text. A site of another client is refused.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "siteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "siteId" ] } } } }, "responses": { "200": { "description": "Set a quote's site", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "connectwiseSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped_by_policy", "succeeded", "failed", "partial_success" ] }, "attempted": { "type": "boolean" }, "message": { "type": "string" }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "attemptedFields": { "type": "array", "items": { "type": "string" } }, "succeededFields": { "type": "array", "items": { "type": "string" } }, "failedFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "inputField": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "inputField", "message" ], "additionalProperties": false } }, "skippedFields": { "type": "array", "items": { "type": "object", "properties": { "inputField": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "message": { "type": "string" } }, "required": [ "inputField", "field", "reason", "message" ], "additionalProperties": false } } }, "required": [ "status", "attempted", "message", "connectwiseOpportunityId", "attemptedFields", "succeededFields", "failedFields", "skippedFields" ], "additionalProperties": false } }, "required": [ "quote", "lineItems", "connectwiseSync" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/contact": { "post": { "operationId": "quote.contact_create_select", "summary": "Create a contact and select it on the quote", "description": "Creates a contact on the quote's client and makes it the quote's contact in one step. It becomes the client's default contact only when the client had none; picking a contact for a quote never creates a second primary.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "firstName": { "type": "string", "maxLength": 500 }, "lastName": { "type": "string", "maxLength": 500 }, "email": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Create a contact and select it on the quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "connectwiseSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped_by_policy", "succeeded", "failed", "partial_success" ] }, "attempted": { "type": "boolean" }, "message": { "type": "string" }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "attemptedFields": { "type": "array", "items": { "type": "string" } }, "succeededFields": { "type": "array", "items": { "type": "string" } }, "failedFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "inputField": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "inputField", "message" ], "additionalProperties": false } }, "skippedFields": { "type": "array", "items": { "type": "object", "properties": { "inputField": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "message": { "type": "string" } }, "required": [ "inputField", "field", "reason", "message" ], "additionalProperties": false } } }, "required": [ "status", "attempted", "message", "connectwiseOpportunityId", "attemptedFields", "succeededFields", "failedFields", "skippedFields" ], "additionalProperties": false }, "contactId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "contactName": { "type": "string" } }, "required": [ "quote", "lineItems", "connectwiseSync", "contactId", "contactName" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/location": { "post": { "operationId": "quote.location_create_select", "summary": "Create a location and select it on the quote", "description": "Creates a site on the quote's client, unlinked from ConnectWise, and makes it the quote's location in one step.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "address": { "type": "string", "maxLength": 500 }, "city": { "type": "string", "maxLength": 500 }, "state": { "type": "string", "maxLength": 500 }, "zipCode": { "type": "string", "maxLength": 500 }, "country": { "type": "string", "maxLength": 500 }, "isPrimary": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Create a location and select it on the quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } }, "connectwiseSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "skipped_by_policy", "succeeded", "failed", "partial_success" ] }, "attempted": { "type": "boolean" }, "message": { "type": "string" }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "attemptedFields": { "type": "array", "items": { "type": "string" } }, "succeededFields": { "type": "array", "items": { "type": "string" } }, "failedFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "inputField": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "inputField", "message" ], "additionalProperties": false } }, "skippedFields": { "type": "array", "items": { "type": "object", "properties": { "inputField": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "message": { "type": "string" } }, "required": [ "inputField", "field", "reason", "message" ], "additionalProperties": false } } }, "required": [ "status", "attempted", "message", "connectwiseOpportunityId", "attemptedFields", "succeededFields", "failedFields", "skippedFields" ], "additionalProperties": false }, "siteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "siteName": { "type": "string" } }, "required": [ "quote", "lineItems", "connectwiseSync", "siteId", "siteName" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/line-items": { "post": { "operationId": "quote.line_item_add", "summary": "Add a line item to a quote", "description": "Adds one product or service line to the end of a quote. Quantity defaults to 1; the billing type decides whether the line recurs and its commitment term. A distributor pricing source (`ingram`, `ingram_cloud`, `cdw`, `pax8`, `tdsynnex`) needs `unitCostMinor`, the cost the distributor quoted, so the line's margin is real. A quote that is Signed, Accepted, or Won is locked and refuses the change. It sets the line's price, so it needs `change_quote_pricing` as well as `edit_quotes`; every member and a `quote:write` key hold both unless an admin denied the member pricing.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0, "maximum": 9999999999 }, "unitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "unitCostMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "description": { "type": "string", "maxLength": 5000 }, "category": { "type": "string", "maxLength": 500 }, "billingType": { "type": "string", "enum": [ "one-time", "monthly", "annual" ] }, "sku": { "type": "string", "maxLength": 500 }, "pricingSource": { "type": "string", "enum": [ "manual", "connectwise", "ingram", "ingram_cloud", "cdw", "pax8", "tdsynnex", "market_reference" ] }, "sourceMetadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "unitPriceMinor" ] } } } }, "responses": { "200": { "description": "Add a line item to a quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/line-items/{lineItemId}": { "patch": { "operationId": "quote.line_item_update", "summary": "Update a quote line item", "description": "Changes one line item's name, quantity, price, cost, description, category, billing type, or pricing provenance. Fields left out keep their value; an empty name keeps the old one. A line whose pricing source is, or becomes, a distributor's needs `unitCostMinor` unless it already carries a nonzero distributor cost, which it keeps. A line inside a bundle takes its quantity from the bundle, so a quantity for one is refused. It needs `change_quote_pricing` as well as `edit_quotes`, whichever fields change.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "lineItemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0, "maximum": 9999999999 }, "unitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "unitCostMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "description": { "type": "string", "maxLength": 5000 }, "category": { "type": "string", "maxLength": 500 }, "billingType": { "type": "string", "enum": [ "one-time", "monthly", "annual" ] }, "pricingSource": { "type": "string", "enum": [ "manual", "connectwise", "ingram", "ingram_cloud", "cdw", "pax8", "tdsynnex", "market_reference" ] }, "sourceMetadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "Update a quote line item", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "delete": { "operationId": "quote.line_item_remove", "summary": "Remove a quote line item", "description": "Deletes one line item from a quote. The quote and every other line keep theirs.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "lineItemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Remove a quote line item", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/discount": { "post": { "operationId": "quote.discount_apply", "summary": "Apply a discount to a quote", "description": "Lowers one line item's unit price by a percentage, or every line's when no line is named, rounding each new price to the cent. It needs `change_quote_pricing`, which every member and a `quote:write` key hold. Setting a line's price directly (`quote.line_item_add`, `quote.line_item_update`) needs it too.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "discountPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "lineItemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "discountPercent" ] } } } }, "responses": { "200": { "description": "Apply a discount to a quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/labor": { "post": { "operationId": "quote.labor_add", "summary": "Add labor to a quote", "description": "Adds a labor line: hours times rate folded into one price at quantity 1, with the hours and the rate kept for display. Without a rate it uses the workspace's default hourly rate from Operations settings, and a workspace with none is refused rather than quoted at zero.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "hours": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, "hourlyRateMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9999999999 }, "category": { "type": "string", "maxLength": 500 } }, "required": [ "description", "hours" ] } } } }, "responses": { "200": { "description": "Add labor to a quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/shipping": { "post": { "operationId": "quote.shipping_add", "summary": "Add shipping to a quote", "description": "Adds a shipping or freight line priced at its cost.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "costMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9999999999 }, "carrier": { "type": "string", "maxLength": 500 } }, "required": [ "description", "costMinor" ] } } } }, "responses": { "200": { "description": "Add shipping to a quote", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "title": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "quoteNumber": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "salesStage": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "clientName": { "type": [ "string", "null" ] }, "siteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "clientLocation": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "opportunityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "connectwiseOpportunityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "probability": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "valueMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "totalAmountMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expirationDate": { "type": [ "string", "null" ] }, "salesRep1": { "type": [ "string", "null" ] }, "salesRep2": { "type": [ "string", "null" ] }, "wonAt": { "type": [ "string", "null" ] }, "lostAt": { "type": [ "string", "null" ] }, "signedOn": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "name", "quoteNumber", "status", "salesStage", "quoteType", "description", "clientId", "clientName", "siteId", "clientLocation", "contactName", "contactEmail", "contactPhone", "opportunityId", "connectwiseOpportunityId", "probability", "currency", "valueMinor", "totalAmountMinor", "expirationDate", "salesRep1", "salesRep2", "wonAt", "lostAt", "signedOn", "createdAt", "updatedAt" ], "additionalProperties": false }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "itemName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedCostMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extendedPriceMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "marginPercentage": { "type": "number" }, "category": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "displayOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "billingFrequency": { "type": [ "string", "null" ] }, "commitmentTerm": { "type": [ "string", "null" ] }, "billingPeriodMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Months between charges for a recurring line: 1 monthly, 2 bi-monthly, 3 quarterly, 6 semi-annual, 12 annual. Null for a one-time line. billingFrequency carries only the nearest of monthly, quarterly and annual, so read this field for the exact cycle." }, "termMonths": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long a recurring line runs, in months. Null for a one-time line. commitmentTerm carries only the nearest of month-to-month, 1-year, 2-year and 3-year, so read this field for the exact term." }, "lineStatus": { "description": "Whether the client takes the line: pending, accepted or declined. Null for a required line on an open quote. An optional add-on is pending until the client decides; on a won quote only accepted lines count toward the totals, and on an open quote every line counts except declined ones.", "type": [ "string", "null" ] }, "isRecurring": { "type": [ "boolean", "null" ] }, "isOptional": { "type": "boolean" }, "lineItemType": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "hourlyRateMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "carrier": { "type": [ "string", "null" ] }, "pricingSource": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "bundleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "bundleUnitQuantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "itemName", "sku", "quantity", "unitCostMinor", "unitPriceMinor", "extendedCostMinor", "extendedPriceMinor", "marginPercentage", "category", "description", "displayOrder", "billingFrequency", "commitmentTerm", "billingPeriodMonths", "termMonths", "lineStatus", "isRecurring", "isOptional", "lineItemType", "hours", "hourlyRateMinor", "carrier", "pricingSource", "vendor", "bundleId", "bundleUnitQuantity" ], "additionalProperties": false } } }, "required": [ "quote", "lineItems" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/sow/restore": { "post": { "operationId": "quote.sow_version_restore", "summary": "Restore a statement of work version", "description": "Overwrites the quote's live statement of work with a previously saved version. The overwrite is itself recorded as a new version, so the replaced content stays in history, but the SOW on the quote, its PDF and the client's view change immediately.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "versionNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 } }, "required": [ "versionNumber" ] } } } }, "responses": { "200": { "description": "Restore a statement of work version", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "sow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "content": { "type": "string" }, "contentFormat": { "type": "string" }, "currentVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sections": {}, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "contentFormat", "currentVersion", "sections", "createdBy", "updatedAt" ], "additionalProperties": false }, "restoredVersionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "quoteId", "url", "sow", "restoredVersionNumber" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/layout": { "patch": { "operationId": "quote.layout_update", "summary": "Update a quote's layout override", "description": "Reorders, hides or reveals the sections of one quote by merging a sparse Quote Layout v2 patch into the quote's own override, or clears the override so the quote falls back to its template. Array entries are matched by id or key; an array entry with neither is refused as ambiguous. The template itself is edited in Settings and is not touched here.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "layoutOverride": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "clearLayoutOverride": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Update a quote's layout override", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "layoutOverride": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "quoteId", "url", "layoutOverride" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } } }, "/v1/quotes/{quoteId}/sow": { "delete": { "operationId": "quote.sow_delete", "summary": "Delete a statement of work", "description": "Permanently deletes the quote's statement of work and its whole version history, and clears the quote's cached PDF. The quote itself is kept. This cannot be undone. A quote with no statement of work answers not_found.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Delete a statement of work", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "sowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionsDeleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "quoteId", "sowId", "versionsDeleted" ], "additionalProperties": false } } } }, "202": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredError" } } } }, "400": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedError" } } } }, "401": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } }, "503": { "description": "Error envelope. `error.code` carries the typed outcome and `error.type` resolves to its description.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } } } } }, "put": { "operationId": "quote.sow_save", "summary": "Save a statement of work", "description": "Replaces the quote's live statement of work, or creates it on the first save. The replaced content stays in the SOW's version history, but the SOW on the quote, its PDF and the client's view change immediately. The statement of work is saved as HTML, which is what the editor, the PDF and the client's view show. Send Markdown in content and it is converted: # and ## headings become sections, and lists, bold, italic and links carry over. With sections (HTML bodies), content must be exactly the HTML they flatten to. To propose a change for a person to review instead, use quote.sow_draft.", "tags": [ "quote" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Opaque idempotency key, at most 255 characters, scoped to (tenant, principal, operation). A missing key is validation_failed.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "description": "The whole statement of work, at most 2 MB. It is saved as HTML: each section is an

heading followed by its body, and a body can use

,

,