{ "openapi": "3.1.0", "info": { "title": "Light AI API", "version": "2026-11-01", "description": "The Light AI public API: leads in from every channel, Light AI Gen 3.0 mockups generated from the contractor's own credits, quotes and outcomes out to your CRM. API access is included on Pro (Pro, Enterprise and Pro trials: the full API, live and test mode); Free and Plus have no API access, and a partner connection carries a contractor's data only while that contractor is on Pro. Authenticate with `Authorization: Bearer lai_live_…` (or `lai_test_…` for test mode). Partner keys add `Light-AI-Organization: org_…` to act for a connected contractor. All money is `{cents, decimal, currency}`; timestamps are RFC 3339 UTC. Errors are RFC 9457 problem details with a stable `code`.", "contact": { "name": "Light AI developer support", "url": "https://docs.light-ai.app", "email": "support@light-ai.app" }, "termsOfService": "https://docs.light-ai.app/terms" }, "externalDocs": { "description": "Guides, recipes and webhook verification", "url": "https://docs.light-ai.app" }, "servers": [ { "url": "https://api.light-ai.app", "description": "Production (live and test keys)" }, { "url": "https://light-ai.app/api", "description": "Alternate host" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Status and the identity of the presented credential." }, { "name": "Leads", "description": "Inbound estimate requests from every channel, deduplicated into touches." }, { "name": "Clients", "description": "Customers and their properties." }, { "name": "Projects", "description": "Jobs in the pipeline. The project id is the stable key across quote revisions." }, { "name": "Quotes", "description": "Published quotes with line items, totals, deposit, assets and outcomes." }, { "name": "Mockups", "description": "Lighting mockups generated with Light AI Gen 3.0 (`light-ai-gen-3.0`), exactly as in the app: 5 credits per image from the contractor's own credits (402 `insufficient_credits` with the credits required and a top-up link when short, plus the balance for organization keys only; a failed image is refunded), results saved to the project's mockup history. Generation is asynchronous: create returns 202 with a `mgen_…` operation; poll GET /v1/mockup_generations/{id} or subscribe to mockup.completed / mockup.failed. Test keys simulate a generation (a sample image; no credits)." }, { "name": "Website forms", "description": "Website request forms installed on contractors' sites (Pro). Every submission is a lead with source `website_widget`, `form`, `form_answers`, `mockup_status`, `preview_looks` and `assets`; `lead.mockup_ready` fires when its optional instant preview finishes (one AI mockup per request at 5 credits from the contractor's credits, capped per form each month; the form hides the preview when credits or caps run out)." }, { "name": "Events", "description": "Everything that happened, for polling (sync_asc) or debugging." }, { "name": "Webhooks", "description": "Signed (Standard Webhooks) event delivery with retries, logs and replay. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first." }, { "name": "Inbound", "description": "Receivers for lead sources that cannot call the API with a key." }, { "name": "Partners", "description": "Integrators serving many contractors through consented grants." }, { "name": "Test mode", "description": "Simulations available to test keys only." } ], "paths": { "/v1/status": { "get": { "operationId": "getStatus", "tags": [ "Account" ], "summary": "API status", "description": "Unauthenticated liveness check (no database access). `HEAD` works here and on every GET route (uptime monitors).", "parameters": [], "responses": { "200": { "description": "The API is up.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiStatus" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/status\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/status', {\n method: 'GET',\n headers: {\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/status\",\n headers={\n },\n timeout=30,\n)\ndata = response.json()" } ], "security": [] } }, "/v1/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Who am I", "description": "The credential's organization (or partner), effective scopes (key ∩ grant ∩ plan), entitlements, limits and API version. Doubles as an authenticated health check. Partner keys add `Light-AI-Organization` to see one connected organization.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The principal.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/me\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/me', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/me\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported" } }, "/v1/test_helpers/leads/{lead_id}/{action}": { "post": { "operationId": "runTestHelper", "tags": [ "Test mode" ], "summary": "Simulate a quote lifecycle step for a test lead", "description": "Test keys only. `publish_quote` publishes a test quote for a lead your test key created (optionally from your own quote-website-v1 `document`); `view_quote`, `click_external_link`, `approve_quote` and `decline_quote` then emit the same events a real homeowner would cause, to your test endpoints only.", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "A test lead id (`lead_…`).", "schema": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" } }, { "name": "action", "in": "path", "required": true, "description": "The step to simulate.", "schema": { "type": "string", "enum": [ "publish_quote", "view_quote", "click_external_link", "approve_quote", "decline_quote" ] } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The test quote after the step.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/test_helpers/leads/{lead_id}/{action}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/test_helpers/leads/{lead_id}/{action}', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/test_helpers/leads/{lead_id}/{action}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "test_only", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestHelperRequest" } } } } } }, "/v1/inbound/{source_id}": { "post": { "operationId": "receiveInboundLead", "tags": [ "Inbound" ], "summary": "Receive a lead (inbound source, header secret)", "description": "For HighLevel workflows, Zapier, Make, n8n, Sweep&Go and form tools. Authenticate with `Authorization: Bearer lai_whin_…` or `X-Light-AI-Source-Secret`. The body is either the POST /v1/leads shape or any JSON your source's field map understands. Always receipt-only. Per-source limits: 60/min and the daily limit. Only the contact can refuse a lead (a name, and an email or a phone): a country name is normalized (`United States` → `US`), and an address or other optional part that cannot be used is left out (its raw value kept in `custom_fields.inbound_*`) instead of losing the lead.", "parameters": [ { "name": "source_id", "in": "path", "required": true, "description": "The inbound source id (`src_…`).", "schema": { "type": "string", "pattern": "^src_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Received (identical for new, repeat and replayed leads).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/inbound/{source_id}\" \\\n -H \"Authorization: Bearer lai_whin_…\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/inbound/{source_id}', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/inbound/{source_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported", "security": [ { "inboundSecret": [] }, { "inboundSecretHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateLeadRequest" }, { "type": "object", "description": "Any JSON object the source's field map maps." } ] }, "example": { "contact": { "first_name": "Dana", "last_name": "Reyes", "email": "dana@example.com", "phone": "+1 (512) 555-0134" }, "address": { "line1": "4102 Oak Hollow Dr", "city": "Austin", "region": "TX", "postal_code": "78731" }, "service_interest": "christmas_lights", "message": "Roofline, warm white." } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Flat form fields, mapped by the source's field map." } }, "text/plain": { "schema": { "type": "string", "description": "A JSON object sent with a text/plain label (parsed as JSON)." } } } } } }, "/v1/inbound/{source_id}/{token}": { "post": { "operationId": "receiveInboundLeadUrlSecret", "tags": [ "Inbound" ], "summary": "Receive a lead (inbound source, secret in the URL)", "description": "For senders that cannot set headers. The URL itself is the credential: keep it private and rotate it if it leaks.", "parameters": [ { "name": "source_id", "in": "path", "required": true, "description": "The inbound source id (`src_…`).", "schema": { "type": "string", "pattern": "^src_[0-9a-f]{32}$" } }, { "name": "token", "in": "path", "required": true, "description": "The source's URL token (`lai_whu_…`).", "schema": { "type": "string", "pattern": "^lai_whu_[0-9A-Za-z]{36}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Received (identical for new, repeat and replayed leads).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/inbound/{source_id}/{token}\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/inbound/{source_id}/{token}', {\n method: 'POST',\n headers: {\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/inbound/{source_id}/{token}\",\n headers={\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline, warm white.\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateLeadRequest" }, { "type": "object", "description": "Any JSON object the source's field map maps." } ] }, "example": { "contact": { "first_name": "Dana", "last_name": "Reyes", "email": "dana@example.com", "phone": "+1 (512) 555-0134" }, "address": { "line1": "4102 Oak Hollow Dr", "city": "Austin", "region": "TX", "postal_code": "78731" }, "service_interest": "christmas_lights", "message": "Roofline, warm white." } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Flat form fields, mapped by the source's field map." } }, "text/plain": { "schema": { "type": "string", "description": "A JSON object sent with a text/plain label (parsed as JSON)." } } } } } }, "/v1/inbound/google-ads/{source_id}": { "post": { "operationId": "receiveGoogleAdsLead", "tags": [ "Inbound" ], "summary": "Google Ads lead form webhook", "description": "Paste this URL and the source key into the lead form's webhook settings. Answers follow Google's retry rules: 200 on success, 400 for a bad key or malformed lead (not retried), 503 when Google should retry (never 429). `is_test` leads (Google's \"Send test data\") run in test mode.", "parameters": [ { "name": "source_id", "in": "path", "required": true, "description": "The inbound source id (`src_…`).", "schema": { "type": "string", "pattern": "^src_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Accepted.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Bad key or malformed lead (Google does not retry).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "503": { "description": "Temporarily unavailable (Google retries).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/inbound/google-ads/{source_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"lead_id\": \"TeSter-123-ABCDEFGHIJKLMNOPQRSTUVWXYZ\",\n \"user_column_data\": [\n {\n \"column_id\": \"FIRST_NAME\",\n \"string_value\": \"Dana\"\n },\n {\n \"column_id\": \"LAST_NAME\",\n \"string_value\": \"Reyes\"\n },\n {\n \"column_id\": \"EMAIL\",\n \"string_value\": \"dana@example.com\"\n },\n {\n \"column_id\": \"PHONE_NUMBER\",\n \"string_value\": \"+15125550134\"\n },\n {\n \"column_id\": \"POSTAL_CODE\",\n \"string_value\": \"78731\"\n }\n ],\n \"google_key\": \"lai_whin_…\",\n \"is_test\": true\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/inbound/google-ads/{source_id}', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"lead_id\": \"TeSter-123-ABCDEFGHIJKLMNOPQRSTUVWXYZ\",\n \"user_column_data\": [\n {\n \"column_id\": \"FIRST_NAME\",\n \"string_value\": \"Dana\"\n },\n {\n \"column_id\": \"LAST_NAME\",\n \"string_value\": \"Reyes\"\n },\n {\n \"column_id\": \"EMAIL\",\n \"string_value\": \"dana@example.com\"\n },\n {\n \"column_id\": \"PHONE_NUMBER\",\n \"string_value\": \"+15125550134\"\n },\n {\n \"column_id\": \"POSTAL_CODE\",\n \"string_value\": \"78731\"\n }\n ],\n \"google_key\": \"lai_whin_…\",\n \"is_test\": true\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/inbound/google-ads/{source_id}\",\n headers={\n },\n json={\n \"lead_id\": \"TeSter-123-ABCDEFGHIJKLMNOPQRSTUVWXYZ\",\n \"user_column_data\": [\n {\n \"column_id\": \"FIRST_NAME\",\n \"string_value\": \"Dana\"\n },\n {\n \"column_id\": \"LAST_NAME\",\n \"string_value\": \"Reyes\"\n },\n {\n \"column_id\": \"EMAIL\",\n \"string_value\": \"dana@example.com\"\n },\n {\n \"column_id\": \"PHONE_NUMBER\",\n \"string_value\": \"+15125550134\"\n },\n {\n \"column_id\": \"POSTAL_CODE\",\n \"string_value\": \"78731\"\n }\n ],\n \"google_key\": \"lai_whin_…\",\n \"is_test\": True\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Google Ads lead form webhook payload (user_column_data, google_key, lead_id, is_test, …)." }, "example": { "lead_id": "TeSter-123-ABCDEFGHIJKLMNOPQRSTUVWXYZ", "user_column_data": [ { "column_id": "FIRST_NAME", "string_value": "Dana" }, { "column_id": "LAST_NAME", "string_value": "Reyes" }, { "column_id": "EMAIL", "string_value": "dana@example.com" }, { "column_id": "PHONE_NUMBER", "string_value": "+15125550134" }, { "column_id": "POSTAL_CODE", "string_value": "78731" } ], "google_key": "lai_whin_…", "is_test": true } } } } } }, "/a/{token}": { "get": { "operationId": "openAssetLink", "tags": [ "Quotes" ], "summary": "Durable quote image link", "description": "Links handed out with the quotes:asset_links scope. Each hit re-checks the issuing key or grant, the organization and the customer link, then redirects (302) to a 60-second signed image URL. Revoking the key or grant, disabling or rotating the customer link, or the 30-day limit stops the link. Query parameters appended by email and marketing tools (utm_*, click ids) are ignored; `HEAD` answers like GET without a body.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The signed link token.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{20,1100}\\.[A-Za-z0-9_-]{43}$" } } ], "responses": { "302": { "description": "Redirect to the image.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/a/{token}\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/a/{token}', {\n method: 'GET',\n headers: {\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/a/{token}\",\n headers={\n },\n timeout=30,\n)\ndata = response.json()" } ], "security": [] } }, "/v1/leads": { "post": { "operationId": "createLead", "tags": [ "Leads" ], "summary": "Create a lead", "description": "Creates an inbound estimate request. Never loses a request: a repeat request for the same address and service on an open lead becomes a **touch** (`lead.touched`, HTTP 200), an `external_ref` your integration already sent replays the original lead (HTTP 200, `replayed: true`), and a paused organization **holds** the lead (converted on resume). \n\nWithout `leads:read` every answer is the same receipt (HTTP 202), so the response never reveals whether a person already exists. A lead without an address is stored and becomes a project when one is added.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "A touch on an open lead, or the replay of your external_ref.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLead200Response" } } } }, "201": { "description": "Lead created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "202": { "description": "Receipt (credential without leads:read).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/leads\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"source\": \"google_lsa\",\n \"source_detail\": \"LSA message lead\",\n \"external_ref\": {\n \"system\": \"google_lsa\",\n \"namespace\": \"ads-123-456-7890\",\n \"id\": \"8813377001\"\n },\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\",\n \"country\": \"US\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline plus the two front trees, warm white.\",\n \"attribution\": {\n \"utm_source\": \"google\",\n \"utm_medium\": \"lsa\",\n \"campaign_id\": \"2093\"\n },\n \"consent\": {\n \"email\": true,\n \"sms\": true,\n \"marketing\": false,\n \"text\": \"I agree to be contacted by text.\",\n \"captured_at\": \"2026-10-12T14:03:11Z\",\n \"method\": \"lsa_message\"\n },\n \"custom_fields\": {\n \"hoa\": \"yes\"\n },\n \"submitted_at\": \"2026-10-12T14:03:11Z\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"source\": \"google_lsa\",\n \"source_detail\": \"LSA message lead\",\n \"external_ref\": {\n \"system\": \"google_lsa\",\n \"namespace\": \"ads-123-456-7890\",\n \"id\": \"8813377001\"\n },\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\",\n \"country\": \"US\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline plus the two front trees, warm white.\",\n \"attribution\": {\n \"utm_source\": \"google\",\n \"utm_medium\": \"lsa\",\n \"campaign_id\": \"2093\"\n },\n \"consent\": {\n \"email\": true,\n \"sms\": true,\n \"marketing\": false,\n \"text\": \"I agree to be contacted by text.\",\n \"captured_at\": \"2026-10-12T14:03:11Z\",\n \"method\": \"lsa_message\"\n },\n \"custom_fields\": {\n \"hoa\": \"yes\"\n },\n \"submitted_at\": \"2026-10-12T14:03:11Z\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/leads\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"source\": \"google_lsa\",\n \"source_detail\": \"LSA message lead\",\n \"external_ref\": {\n \"system\": \"google_lsa\",\n \"namespace\": \"ads-123-456-7890\",\n \"id\": \"8813377001\"\n },\n \"contact\": {\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+1 (512) 555-0134\"\n },\n \"address\": {\n \"line1\": \"4102 Oak Hollow Dr\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\",\n \"country\": \"US\"\n },\n \"service_interest\": \"christmas_lights\",\n \"message\": \"Roofline plus the two front trees, warm white.\",\n \"attribution\": {\n \"utm_source\": \"google\",\n \"utm_medium\": \"lsa\",\n \"campaign_id\": \"2093\"\n },\n \"consent\": {\n \"email\": True,\n \"sms\": True,\n \"marketing\": False,\n \"text\": \"I agree to be contacted by text.\",\n \"captured_at\": \"2026-10-12T14:03:11Z\",\n \"method\": \"lsa_message\"\n },\n \"custom_fields\": {\n \"hoa\": \"yes\"\n },\n \"submitted_at\": \"2026-10-12T14:03:11Z\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadRequest" }, "example": { "source": "google_lsa", "source_detail": "LSA message lead", "external_ref": { "system": "google_lsa", "namespace": "ads-123-456-7890", "id": "8813377001" }, "contact": { "first_name": "Dana", "last_name": "Reyes", "email": "dana@example.com", "phone": "+1 (512) 555-0134" }, "address": { "line1": "4102 Oak Hollow Dr", "city": "Austin", "region": "TX", "postal_code": "78731", "country": "US" }, "service_interest": "christmas_lights", "message": "Roofline plus the two front trees, warm white.", "attribution": { "utm_source": "google", "utm_medium": "lsa", "campaign_id": "2093" }, "consent": { "email": true, "sms": true, "marketing": false, "text": "I agree to be contacted by text.", "captured_at": "2026-10-12T14:03:11Z", "method": "lsa_message" }, "custom_fields": { "hoa": "yes" }, "submitted_at": "2026-10-12T14:03:11Z" } } } } }, "get": { "operationId": "listLeads", "tags": [ "Leads" ], "summary": "List leads", "description": "Newest first by default. For an incremental sync use `sort=updated_asc&updated_since=…`, follow `next_cursor`, and start the next poll a few minutes before your last `updated_at` (de-duplicate by id): a late commit can carry an earlier timestamp. For a gapless change feed poll GET /v1/events?sort=sync_asc.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "sort", "in": "query", "required": false, "description": "`updated_asc` pages objects in last-change order (for an initial or incremental sync with updated_since). A write that commits late can carry an earlier updated_at, so re-poll from your high-water mark minus 5 minutes and de-duplicate by `id` + `updated_at`; GET /v1/events?sort=sync_asc is the gapless change feed.", "schema": { "type": "string", "enum": [ "created_desc", "updated_asc" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "converted", "spam", "archived", "duplicate", "held" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "website_widget", "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other", "manual" ] } }, { "name": "created_after", "in": "query", "required": false, "description": "Only objects created after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only objects created before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects updated after this time (alias: updated_after). Overlap polls by a few minutes: see sort.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "Alias of updated_since.", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_ref", "in": "query", "required": false, "description": "`:` in your own namespace, e.g. `jobber:Z2lk123`.", "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9][a-z0-9_]{1,39}:.{1,255}$" } }, { "name": "external_ref_namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "form_id", "in": "query", "required": false, "description": "Only leads from this website request form (`form_…`).", "schema": { "type": "string", "pattern": "^form_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of leads.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/leads\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/leads\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:read", "x-light-ai-test-mode": "simulated" } }, "/v1/leads/search": { "post": { "operationId": "searchLeads", "tags": [ "Leads" ], "summary": "Search leads by email, phone or address", "description": "Lookups by personal data go in the request body, never the query string. Returns at most 100 matches, newest first.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "Matching leads.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/leads/search\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"dana@example.com\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/search', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"email\": \"dana@example.com\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/leads/search\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"email\": \"dana@example.com\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:read", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "email": "dana@example.com" } } } } } }, "/v1/leads/{lead_id}": { "get": { "operationId": "getLead", "tags": [ "Leads" ], "summary": "Retrieve a lead", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "The lead id (`lead_…`).", "schema": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The lead.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/leads/{lead_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/{lead_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/leads/{lead_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:read", "x-light-ai-test-mode": "simulated" }, "patch": { "operationId": "updateLead", "tags": [ "Leads" ], "summary": "Update a lead", "description": "Change the status (`new`, `archived`, `spam`), notes or reason, or add the street address of a lead that has none yet (no address, or only a ZIP or city): it then converts to a project and `lead.updated` reports the address. Archiving with reason `test` also archives its untouched intake project; nothing is ever deleted. Without `leads:read` only leads your own credential created can be changed, and the answer is a receipt. **Intake-only keys**: address the request by the receipt id `POST /v1/leads` answered with (`/v1/leads/rcpt_…`) to add the address later; a receipt id only takes `address` (and `source_system`) and only changes a lead your credential created. Without `leads:read` every receipt answer is the same 200 receipt (also when the request was folded into someone else's lead, which is never changed, or the lead already has its street address).", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "The lead id (`lead_…`), or the receipt id (`rcpt_…`) your own credential's request was answered with.", "schema": { "type": "string", "pattern": "^(lead|rcpt)_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The updated lead (or a receipt without leads:read).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLead200Response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.light-ai.app/v1/leads/{lead_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"status\": \"archived\",\n \"reason\": \"test\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/{lead_id}', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"status\": \"archived\",\n \"reason\": \"test\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.patch(\n \"https://api.light-ai.app/v1/leads/{lead_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"status\": \"archived\",\n \"reason\": \"test\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadRequest" }, "example": { "status": "archived", "reason": "test" } } } } } }, "/v1/leads/{lead_id}/touches": { "get": { "operationId": "listLeadTouches", "tags": [ "Leads" ], "summary": "List the repeat requests folded into a lead", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "The lead id (`lead_…`).", "schema": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of touches, newest first.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadTouchList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/leads/{lead_id}/touches\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/{lead_id}/touches', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/leads/{lead_id}/touches\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:read", "x-light-ai-test-mode": "simulated" } }, "/v1/clients": { "get": { "operationId": "listClients", "tags": [ "Clients" ], "summary": "List clients", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "sort", "in": "query", "required": false, "description": "`updated_asc` pages objects in last-change order (for an initial or incremental sync with updated_since). A write that commits late can carry an earlier updated_at, so re-poll from your high-water mark minus 5 minutes and de-duplicate by `id` + `updated_at`; GET /v1/events?sort=sync_asc is the gapless change feed.", "schema": { "type": "string", "enum": [ "created_desc", "updated_asc" ] } }, { "name": "created_after", "in": "query", "required": false, "description": "Only objects created after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only objects created before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects updated after this time (alias: updated_after). Overlap polls by a few minutes: see sort.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "Alias of updated_since.", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_ref", "in": "query", "required": false, "description": "`:` in your own namespace, e.g. `jobber:Z2lk123`.", "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9][a-z0-9_]{1,39}:.{1,255}$" } }, { "name": "external_ref_namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of clients.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/clients\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/clients\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:read", "x-light-ai-test-mode": "simulated" }, "post": { "operationId": "upsertClient", "tags": [ "Clients" ], "summary": "Create or update a client", "description": "Matches your own `external_ref` first, then the exact email, then the phone; otherwise creates the client. An `address` adds that property when it is new for the client. Without `clients:read` the answer carries the id only.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Existing client updated.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertClient200Response" } } } }, "201": { "description": "Client created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertClient200Response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/clients\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+15125550134\",\n \"external_ref\": {\n \"system\": \"hubspot\",\n \"id\": \"contact:5501\"\n },\n \"source_system\": \"hubspot\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+15125550134\",\n \"external_ref\": {\n \"system\": \"hubspot\",\n \"id\": \"contact:5501\"\n },\n \"source_system\": \"hubspot\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/clients\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"first_name\": \"Dana\",\n \"last_name\": \"Reyes\",\n \"email\": \"dana@example.com\",\n \"phone\": \"+15125550134\",\n \"external_ref\": {\n \"system\": \"hubspot\",\n \"id\": \"contact:5501\"\n },\n \"source_system\": \"hubspot\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertClientRequest" }, "example": { "first_name": "Dana", "last_name": "Reyes", "email": "dana@example.com", "phone": "+15125550134", "external_ref": { "system": "hubspot", "id": "contact:5501" }, "source_system": "hubspot" } } } } } }, "/v1/clients/search": { "post": { "operationId": "searchClients", "tags": [ "Clients" ], "summary": "Search clients by email, phone or address", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "Matching clients (at most 100).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/clients/search\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"dana@example.com\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/search', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"email\": \"dana@example.com\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/clients/search\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"email\": \"dana@example.com\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:read", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "email": "dana@example.com" } } } } } }, "/v1/clients/{client_id}": { "get": { "operationId": "getClient", "tags": [ "Clients" ], "summary": "Retrieve a client", "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client id (`cli_…`).", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The client.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/clients/{client_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{client_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/clients/{client_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:read", "x-light-ai-test-mode": "simulated" }, "patch": { "operationId": "updateClient", "tags": [ "Clients" ], "summary": "Update a client", "description": "Changes the name, email or phone. `null` (or \"\") clears a field; a null or \"\" `source_system` is absent.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client id (`cli_…`).", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The updated client (id only without clients:read).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertClient200Response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.light-ai.app/v1/clients/{client_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"phone\": \"+15125550199\",\n \"source_system\": \"jobber\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{client_id}', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"phone\": \"+15125550199\",\n \"source_system\": \"jobber\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.patch(\n \"https://api.light-ai.app/v1/clients/{client_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"phone\": \"+15125550199\",\n \"source_system\": \"jobber\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientRequest" }, "example": { "phone": "+15125550199", "source_system": "jobber" } } } } } }, "/v1/clients/{client_id}/properties": { "get": { "operationId": "listClientProperties", "tags": [ "Clients" ], "summary": "List a client's properties", "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client id (`cli_…`).", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The client's properties, primary first.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/clients/{client_id}/properties\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{client_id}/properties', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/clients/{client_id}/properties\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:read", "x-light-ai-test-mode": "simulated" }, "post": { "operationId": "addClientProperty", "tags": [ "Clients" ], "summary": "Add a property to a client", "description": "An identical address returns the existing property. `is_primary` moves the primary flag atomically.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "The client id (`cli_…`).", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The property (id only without clients:read).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddClientProperty201Response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/clients/{client_id}/properties\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"address\": {\n \"line1\": \"88 Lantern Way\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"is_primary\": false\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{client_id}/properties', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"address\": {\n \"line1\": \"88 Lantern Way\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"is_primary\": false\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/clients/{client_id}/properties\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"address\": {\n \"line1\": \"88 Lantern Way\",\n \"city\": \"Austin\",\n \"region\": \"TX\",\n \"postal_code\": \"78731\"\n },\n \"is_primary\": False\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPropertyRequest" }, "example": { "address": { "line1": "88 Lantern Way", "city": "Austin", "region": "TX", "postal_code": "78731" }, "is_primary": false } } } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "tags": [ "Projects" ], "summary": "List projects", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "sort", "in": "query", "required": false, "description": "`updated_asc` pages objects in last-change order (for an initial or incremental sync with updated_since). A write that commits late can carry an earlier updated_at, so re-poll from your high-water mark minus 5 minutes and de-duplicate by `id` + `updated_at`; GET /v1/events?sort=sync_asc is the gapless change feed.", "schema": { "type": "string", "enum": [ "created_desc", "updated_asc" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "intake", "measuring", "mockup", "quote", "approved", "completed", "archived" ] } }, { "name": "pipeline_stage", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "name": "created_after", "in": "query", "required": false, "description": "Only objects created after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only objects created before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects updated after this time (alias: updated_after). Overlap polls by a few minutes: see sort.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "Alias of updated_since.", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_ref", "in": "query", "required": false, "description": "`:` in your own namespace, e.g. `jobber:Z2lk123`.", "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9][a-z0-9_]{1,39}:.{1,255}$" } }, { "name": "external_ref_namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of projects.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/projects\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/projects\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:read", "x-light-ai-test-mode": "simulated" } }, "/v1/projects/{project_id}": { "get": { "operationId": "getProject", "tags": [ "Projects" ], "summary": "Retrieve a project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project id (`prj_…`).", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The project.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/projects/{project_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{project_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/projects/{project_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:read", "x-light-ai-test-mode": "simulated" } }, "/v1/projects/{project_id}/stage": { "post": { "operationId": "moveProjectStage", "tags": [ "Projects" ], "summary": "Move a project to another pipeline stage", "description": "Exactly the manual move a team member can make in the pipeline: a display stage, never an approval (use `mark_approved` for that). `expected_stage` protects against overwriting a newer change (409 `stale_state`).", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project id (`prj_…`).", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The project after the move.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/projects/{project_id}/stage\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"expected_stage\": \"quote_sent\",\n \"stage\": \"closed_lost\",\n \"reason\": \"Went with another company\",\n \"source_system\": \"hubspot\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{project_id}/stage', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"expected_stage\": \"quote_sent\",\n \"stage\": \"closed_lost\",\n \"reason\": \"Went with another company\",\n \"source_system\": \"hubspot\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/projects/{project_id}/stage\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"expected_stage\": \"quote_sent\",\n \"stage\": \"closed_lost\",\n \"reason\": \"Went with another company\",\n \"source_system\": \"hubspot\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveStageRequest" }, "example": { "expected_stage": "quote_sent", "stage": "closed_lost", "reason": "Went with another company", "source_system": "hubspot" } } } } } }, "/v1/pipeline/stages": { "get": { "operationId": "listPipelineStages", "tags": [ "Projects" ], "summary": "Pipeline stage totals", "description": "Project count per stage, and its value with quotes:read. Archived projects are excluded.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "One row per stage.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineStageList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/pipeline/stages\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/pipeline/stages', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/pipeline/stages\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:read", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes": { "get": { "operationId": "listQuotes", "tags": [ "Quotes" ], "summary": "List published quotes", "description": "Drafts are never exposed. With `status` or `is_current` a page may be short (or empty) while `has_more` is true: keep following `next_cursor`. With `quotes:asset_links`, `assets.*.url` are durable image links (as on GET /v1/quotes/{id}).", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "sort", "in": "query", "required": false, "description": "`updated_asc` pages objects in last-change order (for an initial or incremental sync with updated_since). A write that commits late can carry an earlier updated_at, so re-poll from your high-water mark minus 5 minutes and de-duplicate by `id` + `updated_at`; GET /v1/events?sort=sync_asc is the gapless change feed.", "schema": { "type": "string", "enum": [ "created_desc", "updated_asc" ] } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "approved", "declined", "expired", "superseded", "disabled" ] } }, { "name": "is_current", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "created_after", "in": "query", "required": false, "description": "Only quotes created after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only quotes created before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects updated after this time (alias: updated_after). Overlap polls by a few minutes: see sort.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "Alias of updated_since.", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_ref", "in": "query", "required": false, "description": "`:` in your own namespace, e.g. `jobber:Z2lk123`.", "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-z0-9][a-z0-9_]{1,39}:.{1,255}$" } }, { "name": "external_ref_namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of quotes.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/quotes\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/quotes\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:read", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes/{quote_id}": { "get": { "operationId": "getQuote", "tags": [ "Quotes" ], "summary": "Retrieve a quote", "description": "With `quotes:asset_links`, `assets.*.url` are durable links that work while the customer link is active (at most 30 days).", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "The quote id (`qt_…`).", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The quote.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/quotes/{quote_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{quote_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/quotes/{quote_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:read", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes/{quote_id}/assets": { "get": { "operationId": "getQuoteAssets", "tags": [ "Quotes" ], "summary": "Get signed links to a quote's images and PDF", "description": "Fresh signed URLs valid for 60 minutes. An image that no longer exists is `removed: true` with a null URL. With `quotes:asset_links`, each also has a `durable_url` you can store in a CRM.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "The quote id (`qt_…`).", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The quote's assets.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteAssets" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/quotes/{quote_id}/assets\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{quote_id}/assets', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/quotes/{quote_id}/assets\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:read", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes/{quote_id}/timeline": { "get": { "operationId": "getQuoteTimeline", "tags": [ "Quotes" ], "summary": "A quote's timeline (published, viewed, decided)", "description": "Views require the organization's engagement entitlement; otherwise `engagement_available` is false.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "The quote id (`qt_…`).", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The timeline, oldest first.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteTimeline" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/quotes/{quote_id}/timeline\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{quote_id}/timeline', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/quotes/{quote_id}/timeline\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:read", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes/{quote_id}/mark_approved": { "post": { "operationId": "markQuoteApproved", "tags": [ "Quotes" ], "summary": "Record an approval made outside Light AI", "description": "For a homeowner who approved in your CRM or field app (e.g. Jobber). Works on the current published revision while it is `sent`; 409 `quote_already_decided` if the homeowner already decided in Light AI and 409 `quote_not_current` for an older revision. A different selection creates the approved quote with its own id (`replaces_quote_id`). Emits `quote.approved`. Test keys run the same contract on the quotes test mode created (publish one with `POST /v1/test_helpers/leads/{lead_id}/publish_quote`); events reach test endpoints only.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "The quote id (`qt_…`).", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The approved quote.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/quotes/{quote_id}/mark_approved\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"approved_at\": \"2026-10-14T16:00:00Z\",\n \"external_ref\": {\n \"system\": \"jobber\",\n \"id\": \"Z2lkOi8vSm9iYmVyL1F1b3RlLzE\"\n },\n \"signed_by\": \"Dana Reyes\",\n \"note\": \"Approved in Jobber\",\n \"source_system\": \"jobber\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{quote_id}/mark_approved', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"approved_at\": \"2026-10-14T16:00:00Z\",\n \"external_ref\": {\n \"system\": \"jobber\",\n \"id\": \"Z2lkOi8vSm9iYmVyL1F1b3RlLzE\"\n },\n \"signed_by\": \"Dana Reyes\",\n \"note\": \"Approved in Jobber\",\n \"source_system\": \"jobber\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/quotes/{quote_id}/mark_approved\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"approved_at\": \"2026-10-14T16:00:00Z\",\n \"external_ref\": {\n \"system\": \"jobber\",\n \"id\": \"Z2lkOi8vSm9iYmVyL1F1b3RlLzE\"\n },\n \"signed_by\": \"Dana Reyes\",\n \"note\": \"Approved in Jobber\",\n \"source_system\": \"jobber\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkApprovedRequest" }, "example": { "approved_at": "2026-10-14T16:00:00Z", "external_ref": { "system": "jobber", "id": "Z2lkOi8vSm9iYmVyL1F1b3RlLzE" }, "signed_by": "Dana Reyes", "note": "Approved in Jobber", "source_system": "jobber" } } } } } }, "/v1/quotes/{quote_id}/mark_declined": { "post": { "operationId": "markQuoteDeclined", "tags": [ "Quotes" ], "summary": "Record a decline made outside Light AI", "description": "Same rules as mark_approved. The customer link stops accepting approvals. Emits `quote.declined` (closed-lost). Test keys run the same contract on the quotes test mode created.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "description": "The quote id (`qt_…`).", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The declined quote.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/quotes/{quote_id}/mark_declined\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"Price\",\n \"source_system\": \"jobber\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{quote_id}/mark_declined', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"reason\": \"Price\",\n \"source_system\": \"jobber\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/quotes/{quote_id}/mark_declined\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"reason\": \"Price\",\n \"source_system\": \"jobber\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkDeclinedRequest" }, "example": { "reason": "Price", "source_system": "jobber" } } } } } }, "/v1/catalog": { "get": { "operationId": "listCatalog", "tags": [ "Quotes" ], "summary": "The organization's line-item catalog", "description": "The templates the organization quotes from (built-in ones always included, replaced by the organization's \"My defaults\" copy when it saved one) with each line item's stable `code` (matching `line_items[].code` on quotes) and default price, resolved as the app prices a new quote. Mini lights carry `sqft_per_set`. Never costs.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "Templates and their line items.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/catalog\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/catalog', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/catalog\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:read", "x-light-ai-test-mode": "simulated" } }, "/v1/projects/{project_id}/photo_uploads": { "post": { "operationId": "createPhotoUpload", "tags": [ "Mockups" ], "summary": "Create a photo upload", "description": "A single-use slot for a front photo larger than a JSON body allows (up to 10 MB, JPEG, PNG or WebP): PUT the bytes to `upload_url` with their Content-Type within 2 hours, then name the upload in a generation (`source.type` `photo_upload`). At most 20 open slots and 100 slots a day per organization (429 `photo_uploads_daily`). Uploaded originals are working copies: deleted once used or a few hours after an unused slot expires; the generated mockups stay in the project. Test keys get a simulated slot (no upload URL).", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project id (`prj_…`).", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "201": { "description": "The upload slot.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoUpload" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/projects/{project_id}/photo_uploads\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{project_id}/photo_uploads', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/projects/{project_id}/photo_uploads\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "mockups:write", "x-light-ai-test-mode": "simulated" } }, "/v1/projects/{project_id}/mockups": { "post": { "operationId": "createMockupGeneration", "tags": [ "Mockups" ], "summary": "Generate mockups", "description": "Starts a Light AI Gen 3.0 generation of 1–4 lighting mockups for the project, exactly as the app generates them: from the project's front view and its measured guide lines (default), or from a front photo (`photo_url`, fetched once, or `photo_upload`). Costs 5 credits per image from the contractor's own credits, reserved now: 402 `insufficient_credits` (with `required` and `top_up_url`, plus `balance` for an organization key only: a partner key never sees the contractor's balance) when short, and nothing is charged; a partner key also needs the grant's `mockups:write` and stays within the spend cap the contractor set (402 `partner_spend_cap_reached`). Failed images are refunded. Answers 202 with the generation; poll GET /v1/mockup_generations/{id} or subscribe to mockup.completed and mockup.failed. Idempotency-Key is required: a retry with the same key never charges again. At most 3 generations per organization run at once (429 `rate_limited`, `mockup_concurrency`). Finished images join the project as one editor mockup card (named from its light colors in the app, for example Warm White or Candy Cane, unless the contractor renames it). A card generated from a front photo (`photo_url` or `photo_upload`) is not tied to one of the project's front views: the photo is a working copy, removed a few hours after the generation finishes, so the contractor chooses a front view with a photo for that card before generating more from it in the app. Test keys simulate a finished generation with a sample image (no credits).", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project id (`prj_…`).", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "responses": { "202": { "description": "The generation (queued, or the earlier answer for a retried Idempotency-Key).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockupGeneration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/projects/{project_id}/mockups\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"images\": 2,\n \"style_preset\": \"classic_warm_white\",\n \"ambiance\": {\n \"snow\": true\n }\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{project_id}/mockups', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"images\": 2,\n \"style_preset\": \"classic_warm_white\",\n \"ambiance\": {\n \"snow\": true\n }\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/projects/{project_id}/mockups\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"images\": 2,\n \"style_preset\": \"classic_warm_white\",\n \"ambiance\": {\n \"snow\": True\n }\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "mockups:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMockupGenerationRequest" }, "example": { "images": 2, "style_preset": "classic_warm_white", "ambiance": { "snow": true } } } } } } }, "/v1/mockup_generations/{mockup_generation_id}": { "get": { "operationId": "getMockupGeneration", "tags": [ "Mockups" ], "summary": "Retrieve a mockup generation", "description": "The generation with each image's status. Succeeded images carry a signed URL (WebP, valid for one hour: read it again for a fresh one) and their `mockup_id` in the project's mockup history.", "parameters": [ { "name": "mockup_generation_id", "in": "path", "required": true, "description": "The generation id (`mgen_…`).", "schema": { "type": "string", "pattern": "^mgen_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The generation.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockupGeneration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/mockup_generations/{mockup_generation_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/mockup_generations/{mockup_generation_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/mockup_generations/{mockup_generation_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "mockups:read", "x-light-ai-test-mode": "simulated" } }, "/v1/forms": { "get": { "operationId": "listForms", "tags": [ "Website forms" ], "summary": "List website request forms", "description": "Newest first. Website request forms are live configuration: test keys always get an empty list.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "archived" ] } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of forms.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/forms\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/forms', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/forms\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "forms:read", "x-light-ai-test-mode": "simulated" } }, "/v1/forms/{form_id}": { "get": { "operationId": "getForm", "tags": [ "Website forms" ], "summary": "Retrieve a website request form", "description": "Status, install snippets, allowed websites, fields, consent, questions and instant preview settings with this month's use.", "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The form id (`form_…`).", "schema": { "type": "string", "pattern": "^form_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The form.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/forms/{form_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/forms/{form_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/forms/{form_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "forms:read", "x-light-ai-test-mode": "simulated" }, "patch": { "operationId": "updateForm", "tags": [ "Website forms" ], "summary": "Update a website request form", "description": "Pause or resume, rename, edit the wording, replace the allowed websites, or change the instant preview (on/off; one image per request at 5 credits, `images_per_lead` 1 or 2 is accepted for compatibility and stored as 1; monthly credit cap 5–5000; turning previews on without a cap sets 250). `expected_updated_at` is required (409 `stale_state` when the form changed). Changing the websites or turning previews on sends the account owners a notice and appears in Developers → Activity. Pro only; test keys are refused. Needs `forms:write`, which is never part of a preset.", "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The form id (`form_…`).", "schema": { "type": "string", "pattern": "^form_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The updated form.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.light-ai.app/v1/forms/{form_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"expected_updated_at\": \"2026-10-14T15:02:11.120Z\",\n \"status\": \"paused\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/forms/{form_id}', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"expected_updated_at\": \"2026-10-14T15:02:11.120Z\",\n \"status\": \"paused\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.patch(\n \"https://api.light-ai.app/v1/forms/{form_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"expected_updated_at\": \"2026-10-14T15:02:11.120Z\",\n \"status\": \"paused\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "forms:write", "x-light-ai-test-mode": "unsupported", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFormRequest" }, "example": { "expected_updated_at": "2026-10-14T15:02:11.120Z", "status": "paused" } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "description": "Events of the last 30 days your scopes can read. `events:read` or one of `leads:read`, `clients:read`, `projects:read` or `quotes:read` works: the feed holds only the event types those scopes can read (lead events need `leads:read`, quote events `quotes:read`, and so on). Polling integrations should use `sort=sync_asc`: store `next_cursor` and pass it back as `cursor`; every event appears exactly once (no gaps, even for slow transactions). A partner key without Light-AI-Organization lists events of every connected organization under one cursor, each with its `grant`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "sort", "in": "query", "required": false, "description": "`sync_asc` is the gapless polling order: store next_cursor and pass it back; every event appears exactly once.", "schema": { "type": "string", "enum": [ "created_desc", "sync_asc" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled", "ping" ] } }, { "name": "types", "in": "query", "required": false, "description": "Comma-separated event types.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "created_after", "in": "query", "required": false, "description": "Only events created after this time (first sync_asc poll only).", "schema": { "type": "string", "format": "date-time" } }, { "name": "grant_id", "in": "query", "required": false, "description": "Partner keys: one grant's events.", "schema": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of events.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/events\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/events', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/events\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "events:read", "x-light-ai-test-mode": "simulated" } }, "/v1/events/{event_id}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Retrieve an event", "description": "The object inside an event is rendered now (leads and clients show their current state; quote revisions never change). events:read or one of leads:read, clients:read, projects:read or quotes:read works, as for List events.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "The event id (`evt_…`).", "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The event.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/events/{event_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/events/{event_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/events/{event_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "events:read", "x-light-ai-test-mode": "simulated" } }, "/v1/webhook_endpoints": { "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List your webhook endpoints", "description": "Only endpoints your own credential created through the API (dashboard endpoints are managed in Settings → Developers).", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "Your endpoints.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/webhook_endpoints\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/webhook_endpoints\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported" }, "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Subscribe a webhook endpoint", "description": "REST-hook compatible (Zapier, Make, n8n). Returns the signing secret once (`secret`). Subscribing the same URL and events again returns the same endpoint with a freshly rotated secret (HTTP 200); the previous secret keeps working for 24 hours. A re-subscribe also applies the static_header (e.g. a rotated n8n credential), exclude_own_origin and description it sends; fields it omits keep their stored values. The organization's owners are notified of every endpoint created through the API. Partner keys create an endpoint for one connected organization (send `Light-AI-Organization`); a partner-wide endpoint (every connected organization, with per-organization lanes and optional grant filters) is created by the partner owner in Settings → Developers with a second factor, never with a key, so a leaked key can never open a channel to every contractor at once. While the organization has disabled one of your endpoints to a receiver (status_reason `disabled_by_organization`), creating another to that receiver answers 409 stale_state.", "parameters": [ { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Re-subscribed: same endpoint, rotated secret, the sent static_header, exclude_own_origin and description applied.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "201": { "description": "Endpoint created (with its secret).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/webhook_endpoints\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://hooks.example.com/light-ai\",\n \"events\": [\n \"lead.created\",\n \"quote.approved\"\n ],\n \"description\": \"n8n workflow\",\n \"static_header\": {\n \"name\": \"X-N8N-Auth\",\n \"value\": \"a-long-random-value\"\n },\n \"exclude_own_origin\": true\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"url\": \"https://hooks.example.com/light-ai\",\n \"events\": [\n \"lead.created\",\n \"quote.approved\"\n ],\n \"description\": \"n8n workflow\",\n \"static_header\": {\n \"name\": \"X-N8N-Auth\",\n \"value\": \"a-long-random-value\"\n },\n \"exclude_own_origin\": true\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/webhook_endpoints\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"url\": \"https://hooks.example.com/light-ai\",\n \"events\": [\n \"lead.created\",\n \"quote.approved\"\n ],\n \"description\": \"n8n workflow\",\n \"static_header\": {\n \"name\": \"X-N8N-Auth\",\n \"value\": \"a-long-random-value\"\n },\n \"exclude_own_origin\": True\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" }, "example": { "url": "https://hooks.example.com/light-ai", "events": [ "lead.created", "quote.approved" ], "description": "n8n workflow", "static_header": { "name": "X-N8N-Auth", "value": "a-long-random-value" }, "exclude_own_origin": true } } } } } }, "/v1/webhook_endpoints/{endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Retrieve a webhook endpoint", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The endpoint (never its secret).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported" }, "patch": { "operationId": "updateWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Change the URL, events, description, static header, loop prevention or status. Scopes never grow. An endpoint stopped by a revocation or suspension can be disabled but not re-enabled here (an owner re-affirms it in Settings → Developers). One the organization disabled (status_reason `disabled_by_organization`) can be disabled or edited but not enabled or re-pointed, and no other endpoint can be pointed at its receiver (409 stale_state). A static header never moves to a new URL: a request that changes url on an endpoint with a static header must send static_header again (or null), else 422.", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The updated endpoint.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"events\": [\n \"lead.created\",\n \"lead.touched\",\n \"quote.approved\",\n \"quote.declined\"\n ]\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"events\": [\n \"lead.created\",\n \"lead.touched\",\n \"quote.approved\",\n \"quote.declined\"\n ]\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.patch(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"events\": [\n \"lead.created\",\n \"lead.touched\",\n \"quote.approved\",\n \"quote.declined\"\n ]\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" }, "example": { "events": [ "lead.created", "lead.touched", "quote.approved", "quote.declined" ] } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Unsubscribe (delete) a webhook endpoint", "description": "Pending deliveries are dropped with it. An endpoint the organization disabled (status_reason `disabled_by_organization`) cannot be deleted here (409 stale_state): it stands for their decision until they enable or remove it in Settings → Developers.", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.delete(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported" } }, "/v1/webhook_endpoints/{endpoint_id}/rotate_secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "description": "Returns the new secret once. For 24 hours deliveries carry signatures for both secrets.", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint with its new secret.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/rotate_secret\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/rotate_secret', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/rotate_secret\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/webhook_endpoints/{endpoint_id}/test": { "post": { "operationId": "testWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Queues one `ping` event to this endpoint (at most 30 test sends per hour per organization). In test mode each ping is also one of the organization's 500 test deliveries a day: past that it is refused (429 rate_limited, limit_scope `test_deliveries`, Retry-After until midnight UTC), never answered without a delivery. An endpoint that cannot receive it answers 409 stale_state.", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The queued ping (delivery_id is the delivery to watch).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/test\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/test', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/test\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/webhook_endpoints/{endpoint_id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List an endpoint's deliveries", "description": "Deliveries of the last 30 days with their attempts (status, latency, error class, a short response excerpt).", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "status", "in": "query", "required": false, "description": "The status shown on each delivery: `pending` (not attempted yet) and `retrying` (failed, waiting for its next attempt) are distinct.", "schema": { "type": "string", "enum": [ "pending", "retrying", "leased", "succeeded", "abandoned", "cancelled" ] } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of deliveries, newest first.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/deliveries\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/deliveries', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/deliveries\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported" } }, "/v1/webhook_endpoints/{endpoint_id}/replay": { "post": { "operationId": "replayWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "Replay events to an endpoint", "description": "Re-queues events of a time range (at most 30 days back, at most 5000 events). By default only events not yet delivered successfully, including events missed while the endpoint was disabled. Replays reuse the original `webhook-id`. Test-mode replays count toward the organization's 500 test deliveries a day: a replay that would pass it queues nothing and answers 429 (Retry-After until midnight UTC).", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "The endpoint id (`we_…`).", "schema": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "How many events were queued.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplay" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/replay\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"created_after\": \"2026-10-10T00:00:00Z\",\n \"types\": [\n \"lead.created\"\n ],\n \"only_failed\": true\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/replay', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"created_after\": \"2026-10-10T00:00:00Z\",\n \"types\": [\n \"lead.created\"\n ],\n \"only_failed\": true\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/replay\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"created_after\": \"2026-10-10T00:00:00Z\",\n \"types\": [\n \"lead.created\"\n ],\n \"only_failed\": True\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayDeliveriesRequest" }, "example": { "created_after": "2026-10-10T00:00:00Z", "types": [ "lead.created" ], "only_failed": true } } } } } }, "/v1/webhook_deliveries/{delivery_id}/retry": { "post": { "operationId": "retryWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Retry one delivery now", "description": "Re-queues this delivery's event to its endpoint, reusing its `webhook-id` (a logged `ping` too, to re-verify the receiver). A test-mode retry counts toward the organization's 500 test deliveries a day (429 past it).", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "description": "The delivery id (`whd_…`).", "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Queued (1) or skipped (0).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReplay" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/webhook_deliveries/{delivery_id}/retry\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/webhook_deliveries/{delivery_id}/retry', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/webhook_deliveries/{delivery_id}/retry\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "webhooks:manage", "x-light-ai-test-mode": "supported", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/partner/grants": { "get": { "operationId": "listPartnerGrants", "tags": [ "Partners" ], "summary": "List the organizations connected to your partner account", "description": "Each grant is one contractor's consent. Send `Light-AI-Organization: org_…` with a grant's organization id to act for it.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "active", "revoked", "expired", "superseded", "suspended" ] } }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of grants.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/partner/grants\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/grants', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/partner/grants\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key" } }, "/v1/partner/grants/{grant_id}": { "patch": { "operationId": "updatePartnerGrant", "tags": [ "Partners" ], "summary": "Set your reference and metadata for a connected organization", "description": "`external_reference` (e.g. a HighLevel locationId) is echoed in every event of that organization, for routing.", "parameters": [ { "name": "grant_id", "in": "path", "required": true, "description": "The grant id (`grant_…`).", "schema": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The grant.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.light-ai.app/v1/partner/grants/{grant_id}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"external_reference\": \"ghl-location-AbC123\",\n \"metadata\": {\n \"region\": \"TX\"\n }\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/grants/{grant_id}', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"external_reference\": \"ghl-location-AbC123\",\n \"metadata\": {\n \"region\": \"TX\"\n }\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.patch(\n \"https://api.light-ai.app/v1/partner/grants/{grant_id}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"external_reference\": \"ghl-location-AbC123\",\n \"metadata\": {\n \"region\": \"TX\"\n }\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "unsupported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUpdateGrantRequest" }, "example": { "external_reference": "ghl-location-AbC123", "metadata": { "region": "TX" } } } } } } }, "/v1/partner/grants/{grant_id}/confirm": { "post": { "operationId": "confirmPartnerGrant", "tags": [ "Partners" ], "summary": "Confirm the organization an unbound connect link reached", "description": "A link without a bound organization activates only after you confirm the organization name the owner approved with (shown on the pending grant). Live keys only, holding every scope the grant asks for.", "parameters": [ { "name": "grant_id", "in": "path", "required": true, "description": "The grant id (`grant_…`).", "schema": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The active grant.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/partner/grants/{grant_id}/confirm\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/grants/{grant_id}/confirm', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/partner/grants/{grant_id}/confirm\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "unsupported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/partner/grants/{grant_id}/decline": { "post": { "operationId": "declinePartnerGrant", "tags": [ "Partners" ], "summary": "Decline a pending grant (wrong organization)", "parameters": [ { "name": "grant_id", "in": "path", "required": true, "description": "The grant id (`grant_…`).", "schema": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The revoked grant.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/partner/grants/{grant_id}/decline\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/grants/{grant_id}/decline', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/partner/grants/{grant_id}/decline\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "unsupported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/partner/connect_links": { "get": { "operationId": "listConnectLinks", "tags": [ "Partners" ], "summary": "List your connect links", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string", "maxLength": 400 } }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "A page of links, newest first.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectLinkList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.light-ai.app/v1/partner/connect_links\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/connect_links', {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.get(\n \"https://api.light-ai.app/v1/partner/connect_links\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "supported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key" }, "post": { "operationId": "createConnectLink", "tags": [ "Partners" ], "summary": "Create a connect link", "description": "A single-use link (7 days at most) a contractor's owner opens to approve your access. The owner signs in (or signs up), sees your verified legal name, domain and every scope, and approves. Never email API keys: send connect links. The `url` is returned only here (and on an Idempotency-Key replay).", "parameters": [ { "$ref": "#/components/parameters/VersionHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The link (with its url).", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/partner/connect_links\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"scopes\": [\n \"leads:read\",\n \"leads:write\",\n \"clients:read\",\n \"projects:read\",\n \"quotes:read\",\n \"quotes:write\",\n \"webhooks:manage\"\n ],\n \"client_label\": \"Bright Nights Lighting\",\n \"external_reference\": \"ghl-location-AbC123\",\n \"redirect_uri\": \"https://app.acme-automations.com/light-ai/connected\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/connect_links', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Idempotency-Key': crypto.randomUUID(),\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"scopes\": [\n \"leads:read\",\n \"leads:write\",\n \"clients:read\",\n \"projects:read\",\n \"quotes:read\",\n \"quotes:write\",\n \"webhooks:manage\"\n ],\n \"client_label\": \"Bright Nights Lighting\",\n \"external_reference\": \"ghl-location-AbC123\",\n \"redirect_uri\": \"https://app.acme-automations.com/light-ai/connected\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/partner/connect_links\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n \"Idempotency-Key\": str(uuid.uuid4()),\n },\n json={\n \"scopes\": [\n \"leads:read\",\n \"leads:write\",\n \"clients:read\",\n \"projects:read\",\n \"quotes:read\",\n \"quotes:write\",\n \"webhooks:manage\"\n ],\n \"client_label\": \"Bright Nights Lighting\",\n \"external_reference\": \"ghl-location-AbC123\",\n \"redirect_uri\": \"https://app.acme-automations.com/light-ai/connected\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "unsupported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectLinkRequest" }, "example": { "scopes": [ "leads:read", "leads:write", "clients:read", "projects:read", "quotes:read", "quotes:write", "webhooks:manage" ], "client_label": "Bright Nights Lighting", "external_reference": "ghl-location-AbC123", "redirect_uri": "https://app.acme-automations.com/light-ai/connected" } } } } } }, "/v1/partner/connect_links/{connect_link_id}/revoke": { "post": { "operationId": "revokeConnectLink", "tags": [ "Partners" ], "summary": "Revoke an unused connect link", "parameters": [ { "name": "connect_link_id", "in": "path", "required": true, "description": "The link id (`cl_…`).", "schema": { "type": "string", "pattern": "^cl_[0-9a-f]{32}$" } }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The revoked link.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.light-ai.app/v1/partner/connect_links/{connect_link_id}/revoke\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/partner/connect_links/{connect_link_id}/revoke', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.post(\n \"https://api.light-ai.app/v1/partner/connect_links/{connect_link_id}/revoke\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-test-mode": "unsupported", "security": [ { "apiKey": [] } ], "x-light-ai-principal": "partner_key", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } } } }, "/v1/leads/{object_id}/external_refs/{system}": { "put": { "operationId": "putLeadExternalRef", "tags": [ "Leads" ], "summary": "Set your id for a lead", "description": "Writes back your CRM id. References are namespaced by integration: you can never overwrite another integration's ids.", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The lead id, or the receipt id (`rcpt_…`) of your own credential's request.", "schema": { "type": "string", "pattern": "^(lead|rcpt)_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT \"https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}', {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.put(\n \"https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutExternalRefRequest" }, "example": { "id": "Z2lkOi8vSm9iYmVy" } } } } }, "delete": { "operationId": "deleteLeadExternalRef", "tags": [ "Leads" ], "summary": "Remove your id for a lead", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The lead id, or the receipt id (`rcpt_…`) of your own credential's request.", "schema": { "type": "string", "pattern": "^(lead|rcpt)_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's remaining external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.delete(\n \"https://api.light-ai.app/v1/leads/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "leads:write", "x-light-ai-test-mode": "simulated" } }, "/v1/clients/{object_id}/external_refs/{system}": { "put": { "operationId": "putClientExternalRef", "tags": [ "Clients" ], "summary": "Set your id for a client", "description": "Writes back your CRM id. References are namespaced by integration: you can never overwrite another integration's ids.", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The client id.", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT \"https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}', {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.put(\n \"https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutExternalRefRequest" }, "example": { "id": "Z2lkOi8vSm9iYmVy" } } } } }, "delete": { "operationId": "deleteClientExternalRef", "tags": [ "Clients" ], "summary": "Remove your id for a client", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The client id.", "schema": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's remaining external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.delete(\n \"https://api.light-ai.app/v1/clients/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "clients:write", "x-light-ai-test-mode": "simulated" } }, "/v1/projects/{object_id}/external_refs/{system}": { "put": { "operationId": "putProjectExternalRef", "tags": [ "Projects" ], "summary": "Set your id for a project", "description": "Writes back your CRM id. References are namespaced by integration: you can never overwrite another integration's ids.", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The project id.", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT \"https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}', {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.put(\n \"https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutExternalRefRequest" }, "example": { "id": "Z2lkOi8vSm9iYmVy" } } } } }, "delete": { "operationId": "deleteProjectExternalRef", "tags": [ "Projects" ], "summary": "Remove your id for a project", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The project id.", "schema": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's remaining external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.delete(\n \"https://api.light-ai.app/v1/projects/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "projects:write", "x-light-ai-test-mode": "simulated" } }, "/v1/quotes/{object_id}/external_refs/{system}": { "put": { "operationId": "putQuoteExternalRef", "tags": [ "Quotes" ], "summary": "Set your id for a quote", "description": "Writes back your CRM id. References are namespaced by integration: you can never overwrite another integration's ids.", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The quote id.", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT \"https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n}'" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}', {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n }),\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.put(\n \"https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n json={\n \"id\": \"Z2lkOi8vSm9iYmVy\"\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:write", "x-light-ai-test-mode": "simulated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutExternalRefRequest" }, "example": { "id": "Z2lkOi8vSm9iYmVy" } } } } }, "delete": { "operationId": "deleteQuoteExternalRef", "tags": [ "Quotes" ], "summary": "Remove your id for a quote", "parameters": [ { "name": "object_id", "in": "path", "required": true, "description": "The quote id.", "schema": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" } }, { "name": "system", "in": "path", "required": true, "description": "Lowercase system name, e.g. `jobber`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" } }, { "name": "namespace", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/OrganizationHeader" }, { "$ref": "#/components/parameters/VersionHeader" } ], "responses": { "200": { "description": "The object's remaining external references.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRefList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}\" \\\n -H \"Authorization: Bearer $LIGHT_AI_API_KEY\"" }, { "lang": "javascript", "label": "Node.js", "source": "const response = await fetch('https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}`,\n },\n});\nconst data = await response.json();" }, { "lang": "python", "label": "Python", "source": "import os, uuid, requests\n\nresponse = requests.delete(\n \"https://api.light-ai.app/v1/quotes/{object_id}/external_refs/{system}\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['LIGHT_AI_API_KEY']}\",\n },\n timeout=30,\n)\ndata = response.json()" } ], "x-light-ai-scope": "quotes:write", "x-light-ai-test-mode": "simulated" } } }, "webhooks": { "lead.created": { "post": { "summary": "lead.created event", "description": "A new lead (any channel), once per lead. needs_address true when it waits for an address. Spam and blocked website repeats are not leads; one that is later reopened as a live lead is announced then (within 30 days of the request). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "lead.created" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCreatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "lead.touched": { "post": { "summary": "lead.touched event", "description": "A repeat request folded into an existing lead (API, inbound, or a website request blocked as a repeat of an earlier one): data.touch is the new request. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "lead.touched" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadTouchedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "lead.updated": { "post": { "summary": "lead.updated event", "description": "Status, hold or address change (archived, spam, reopened, held → converted, address added → converted). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "lead.updated" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadUpdatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "lead.mockup_ready": { "post": { "summary": "lead.mockup_ready event", "description": "A website request form lead's instant preview step finished (sent once, after lead.created, never delaying it): data.object.mockup_status is ready, failed or skipped. It fires once the request's one preview is settled (or 30 minutes after the request), so data.object.assets.mockups and preview_looks list it (older leads may list up to 3). Image URLs are not in the payload: GET /v1/leads/{id} returns data.object.assets with 60-minute signed links. Origin type is always `embed`. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "lead.mockup_ready" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadMockupReadyEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "client.created": { "post": { "summary": "client.created event", "description": "A new client. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "client.created" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCreatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "client.updated": { "post": { "summary": "client.updated event", "description": "Name, email or phone changed, or a property was added, edited or removed or the primary property changed (previous_attributes.updated_fields: first_name, last_name, email, phone, properties, primary_property), or another client was merged into this one (updated_fields `merged`: its client.deleted names this client in merged_into). Coalesced per client, per origin and per minute, trailing edge: a webhook endpoint gets one delivery per window, sent at its end and showing the client as it is then. A recorded event is never changed: a later edit in the same minute is a new client.updated (updated_fields lists every field the window changed so far), so the events feed can list more than one per minute, and an earlier delivery not yet sent is cancelled (superseded) in favor of the new one. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "client.updated" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUpdatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "client.deleted": { "post": { "summary": "client.deleted event", "description": "A client was deleted: id and external refs only. merged_into is set when the contractor merged it into an existing client (re-point your records to that client). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "client.deleted" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientDeletedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "project.created": { "post": { "summary": "project.created event", "description": "A new project (from a lead with an address, or created in the app). A website request blocked as a repeat still gets its own project in the app: its lead is that request (status `duplicate`), announced as lead.touched on the earlier lead. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "project.created" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "project.stage_changed": { "post": { "summary": "project.stage_changed event", "description": "The pipeline stage changed (a move, a quote or approval, a saved measurement in the app, a deleted draft quote). data.stage_change is the transition at event time ({from, to, sequence}); trigger on data.stage_change.to, not on data.object.pipeline_stage (the current stage). previous_attributes.pipeline_stage equals stage_change.from. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "project.stage_changed" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectStageChangedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.published": { "post": { "summary": "quote.published event", "description": "A quote revision was published (a new quote id; key CRM records on project.id). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.published" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotePublishedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.viewed": { "post": { "summary": "quote.viewed event", "description": "The homeowner opened the quote (needs the engagement entitlement). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.viewed" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteViewedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.external_link_clicked": { "post": { "summary": "quote.external_link_clicked event", "description": "The homeowner clicked the quote's external link. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.external_link_clicked" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteExternalLinkClickedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.change_requested": { "post": { "summary": "quote.change_requested event", "description": "The homeowner used \"Request a change\" on the quote link (the contractor turned on Let customers request changes for this quote): data.change_request is the request ({id, message, created_at}). One event per request; the quote stays sent and can still be approved, and the pipeline stage does not change. A homeowner has one open request per quote link at a time (the next is possible once the contractor marks it resolved, publishes an update or after 24 hours). Live mode only: test mode cannot simulate it. Origin type is `portal`. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.change_requested" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteChangeRequestedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.approved": { "post": { "summary": "quote.approved event", "description": "Approved by the homeowner, in the app, or recorded with mark_approved. An approval with a different selection of optional items approves a new quote (replaces_quote_id names the published one), announced first by quote.superseded for the published quote (superseded_by this one), live and in test mode alike. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.approved" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteApprovedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.declined": { "post": { "summary": "quote.declined event", "description": "Declined (maps to closed-lost). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.declined" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDeclinedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.expired": { "post": { "summary": "quote.expired event", "description": "The link expired without a decision (maps to closed-lost). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.expired" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteExpiredEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.link_disabled": { "post": { "summary": "quote.link_disabled event", "description": "The quote's customer link stopped working. previous_attributes.reason says why: `disabled` (the contractor turned the link off) or `rotated` (the contractor issued a new link: the old one is dead, and data.object.links.customer_url carries the new one when you hold quotes:share_link; re-read the quote rather than marking its link dead). A `disabled` link can be turned back on: quote.link_enabled follows. Rotating a disabled link sends `rotated`, then quote.link_enabled (the new link works). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.link_disabled" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteLinkDisabledEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.link_enabled": { "post": { "summary": "quote.link_enabled event", "description": "A disabled customer link works again: the contractor turned the same link back on, or rotated it (a new link, announced first by quote.link_disabled `rotated`; re-read customer_url). data.object.status is current; previous_attributes.status is `disabled`. Resume follow-ups you stopped on quote.link_disabled. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.link_enabled" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteLinkEnabledEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "quote.superseded": { "post": { "summary": "quote.superseded event", "description": "This quote was replaced (superseded_by names the replacement): the contractor published a newer revision, or the quote was approved with a changed selection of optional items, which approves a new quote (its quote.approved follows). Close this quote in your system and link the replacement. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first. A quote too large for one delivery (256 KB) arrives with `truncated: true` and empty `line_items`: read the full quote with GET /v1/quotes/{id} before mapping its lines.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.superseded" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSupersededEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "mockup.completed": { "post": { "summary": "mockup.completed event", "description": "A mockup generation finished with at least one image (images[].status says which; failed images were refunded). Image URLs are not in the payload: GET /v1/mockup_generations/{id} for signed URLs. Needs mockups:read. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "mockup.completed" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockupCompletedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "mockup.failed": { "post": { "summary": "mockup.failed event", "description": "A mockup generation finished without any image; every credit was refunded (failure_code says why). Needs mockups:read. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "mockup.failed" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockupFailedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "organization.entitlement_changed": { "post": { "summary": "organization.entitlement_changed event", "description": "Plan, pause, Off-Season, kill-switch or quote-engagement change (delivered even when it ends your access). paused and off_season are what is in effect: a seasonal pause or Off-Season scheduled ahead is announced when it starts (within the hour), not when it is scheduled; while paused the organization is read-only and inbound leads are held. previous_attributes holds the earlier tier, paused, api_disabled, off_season and engagement. engagement turns off while a payment is past due (the tier stays): quote.viewed and quote.external_link_clicked stop until it turns on again. API access is included on Pro: Pro, Enterprise and Pro trials have the full API; Free and Plus have none (tier names the plan; live_api, test_mode and the rest are false). A drop below Pro suspends the organization's keys, sources and endpoints (never deleted) right after this event, and a partner's grant carries none of its data; an upgrade to Pro restores them. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "organization.entitlement_changed" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEntitlementChangedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "grant.created": { "post": { "summary": "grant.created event", "description": "A contractor connected your partner account. Sent once per grant status: with data.object.status `pending` when a grant awaits your confirmation (POST /v1/partner/grants/{id}/confirm), and again with `active` once it is confirmed (a grant that starts active gets only that one). Provision on data.object.id with status `active`; the two deliveries have different event ids. A contractor that re-consents (new scopes) gets a new grant: data.object.replaces_grant_id names the grant it supersedes, so re-map that contractor (or de-duplicate on organization_id) rather than provisioning it twice. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "grant.created" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "grant.revoked": { "post": { "summary": "grant.revoked event", "description": "A contractor's grant ended (revoked or expired); delivered as a farewell. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "grant.revoked" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRevokedEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "api_key.expiring": { "post": { "summary": "api_key.expiring event", "description": "Sent 14 and 3 days before the key expires, to that key's own endpoints (a partner key: the partner's endpoints) that subscribe to it (list it in events, or use [\"*\"]). The owners also get an e-mail. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "api_key.expiring" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyExpiringEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "webhook_endpoint.disabled": { "post": { "summary": "webhook_endpoint.disabled event", "description": "Another endpoint of the same owner was disabled by Light AI: a key's endpoint notifies that key's other endpoints, a partner's notifies the partner's endpoints, a dashboard endpoint the organization's other dashboard endpoints; only endpoints that subscribe to it (list it in events, or use [\"*\"]) receive it. The owners also get an e-mail. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "webhook_endpoint.disabled" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDisabledEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } }, "ping": { "post": { "summary": "ping event", "description": "Test delivery (only to the endpoint it was sent to). Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Respond 2xx within 10 seconds. Delivery is at-least-once: the same event can arrive more than once (a retry after a timeout, a replay), always with the same webhook-id, so de-duplicate on webhook-id. Order is not guaranteed: a retried event can arrive after a later one, so compare data.object.updated_at (and data.stage_change.sequence for project.stage_changed) with what you stored and skip older ones. data.object is the object as it is when the delivery is sent: upsert by its id rather than assuming an earlier event arrived first.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event id; constant across retries." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds." }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Space-separated `v1,` signatures over `{id}.{timestamp}.{body}`." }, { "name": "Light-AI-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "ping" ] } }, { "name": "Light-AI-Delivery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, { "name": "Light-AI-Organization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." }, "410": { "description": "Gone: disables the endpoint immediately." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "lai_live_… | lai_test_…", "description": "Organization or partner API key. Keys are shown once when created in Settings → Developers." }, "inboundSecret": { "type": "http", "scheme": "bearer", "bearerFormat": "lai_whin_…", "description": "Inbound source secret." }, "inboundSecretHeader": { "type": "apiKey", "in": "header", "name": "X-Light-AI-Source-Secret", "description": "Inbound source secret." } }, "parameters": { "OrganizationHeader": { "name": "Light-AI-Organization", "in": "header", "required": false, "description": "Partner keys: the connected organization to act for (`org_…`). Organization keys may omit it.", "schema": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" } }, "VersionHeader": { "name": "Light-AI-Version", "in": "header", "required": false, "description": "Pin a dated API version (defaults to the key's version).", "schema": { "type": "string", "enum": [ "2026-11-01" ] } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry-safe writes: the same key and body replay the first response for 24 hours (`Idempotent-Replayed: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" } }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required: one key per logical request. A retry with the same key and body returns the same operation and never charges again (permanently, not only for 24 hours); the same key with a different body is 422 `idempotency_key_reused`.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" } } }, "responses": { "BadRequest": { "description": "Bad request (bad_request, test_mode_mismatch, test_mode_unsupported, unsupported_api_version).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unauthorized": { "description": "Missing or invalid credential (authentication_required, invalid_api_key, api_key_revoked, api_key_expired, api_key_suspended).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "PaymentRequired": { "description": "Not enough credits (insufficient_credits: `required` and `top_up_url`, plus `balance` for organization keys only; a partner key never sees the contractor's balance), or a partner spend cap the organization set (partner_spend_cap_reached). Nothing was charged.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Forbidden": { "description": "Not allowed (insufficient_scope, plan_upgrade_required, organization_paused, organization_off_season, api_disabled, api_access_not_enabled, ip_not_allowed, forbidden).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "NotFound": { "description": "Not found (also for objects of other organizations and for organizations without an active grant).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Conflict": { "description": "Conflict (stale_state, conflict, idempotency_in_progress, idempotency_scope_mismatch, quote_already_decided, quote_not_current, billing_review_required, limit_reached: a standing limit such as the webhook endpoint cap; free capacity instead of retrying).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "PayloadTooLarge": { "description": "Request bodies are limited to 256 KB.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "UnsupportedMediaType": { "description": "The body is not JSON (unsupported_media_type): send Content-Type: application/json.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "ValidationFailed": { "description": "Validation failed (validation_failed with errors[] JSON pointers, idempotency_key_reused).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "RateLimited": { "description": "Rate limited or daily cap reached (rate_limited, daily_cap_reached). See Retry-After and the RateLimit headers.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "Unavailable": { "description": "Temporarily unavailable (service_unavailable). Retry with exponential backoff.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "InternalError": { "description": "Unexpected server error (internal_error). Safe to retry with exponential backoff; quote the Request-Id to support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "MethodNotAllowed": { "description": "This path does not support the method (method_not_allowed); the Allow header lists the methods it does.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "description": "The methods this path supports.", "schema": { "type": "string" } } } } }, "headers": { "RequestId": { "description": "Unique id of this request (quote it to support).", "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$" } }, "IdempotentReplayed": { "description": "`true` when the response is a stored Idempotency-Key replay.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "AddClientProperty201Response": { "anyOf": [ { "$ref": "#/components/schemas/Property" }, { "$ref": "#/components/schemas/PropertyReference" } ] }, "AddPropertyRequest": { "type": "object", "properties": { "address": { "description": "A street address. A ZIP-, city- or region-only address is refused (422 at /address).", "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "region": { "description": "State or region, e.g. `TX`.", "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "country": { "description": "ISO 3166-1 alpha-2 in any case, or a common name (\"USA\", \"United States\"); normalized to alpha-2. Defaults to US.", "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "formatted": { "description": "A one-line address, when components are not available.", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lat": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] }, "place_id": { "description": "Google place id, when known (best dedupe key).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] } }, "additionalProperties": false }, "property_type": { "type": "string", "maxLength": 50 }, "is_primary": { "description": "Make this the client's primary property.", "type": "boolean" } }, "required": [ "address" ], "additionalProperties": false }, "Address": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formatted": { "description": "Always present. Components may be null for addresses entered as one line.", "type": "string" }, "lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country", "formatted", "lat", "lng" ] }, "AddressInput": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "region": { "description": "State or region, e.g. `TX`.", "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "country": { "description": "ISO 3166-1 alpha-2 in any case, or a common name (\"USA\", \"United States\"); normalized to alpha-2. Defaults to US.", "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "formatted": { "description": "A one-line address, when components are not available.", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lat": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] }, "place_id": { "description": "Google place id, when known (best dedupe key).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] } }, "additionalProperties": false }, "ApiKeyExpiring": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "api_key" }, "name": { "type": "string" }, "expires_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "days_remaining": { "description": "Whole days until expires_at, rounded up (a key created to last 10 days says 10).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" } }, "required": [ "id", "object", "name", "expires_at", "days_remaining", "livemode" ] }, "ApiKeyExpiringEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "api_key.expiring" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ApiKeyExpiring" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "ApiStatus": { "type": "object", "properties": { "object": { "type": "string", "const": "status" }, "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string" } }, "required": [ "object", "ok", "api_version" ] }, "CatalogList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogTemplate" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "CatalogTemplate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tpl_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "catalog_template" }, "name": { "type": "string" }, "service_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_system": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "fixture": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "measurement_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "description": "The pricing unit of unit_price.", "anyOf": [ { "type": "string", "enum": [ "ft", "sqft", "each", "set" ] }, { "type": "null" } ] }, "unit_price": { "description": "The default price a new quote starts from: the template's own pricing, else the organization's saved defaults, else Light AI's defaults. Per foot for C9, per set for mini lights; null for custom items (priced per quote).", "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "sqft_per_set": { "description": "Mini lights only: the square feet one set covers. Quote lines measure mini lights in square feet; sets = ceil(quantity / sqft_per_set). Null for other items.", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] } }, "required": [ "code", "name", "description", "category", "measurement_type", "unit", "unit_price", "sqft_per_set" ] } } }, "required": [ "id", "object", "name", "service_type", "is_default", "is_system", "items" ] }, "Client": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "client" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "E.164, or null when the stored number could not be normalized (see phone_raw).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone_raw": { "description": "The number as stored in Light AI.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_property": { "anyOf": [ { "$ref": "#/components/schemas/Property" }, { "type": "null" } ] }, "property_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "fixture": { "type": "boolean", "const": true } }, "required": [ "id", "object", "livemode", "first_name", "last_name", "email", "phone", "phone_raw", "primary_property", "property_count", "external_refs", "created_at", "updated_at" ] }, "ClientCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "client.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Client" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "ClientDeletedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "client.deleted" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ClientTombstone" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "ClientList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "ClientReference": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "client" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" } }, "required": [ "id", "object", "livemode" ] }, "ClientTombstone": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "client" }, "deleted": { "type": "boolean", "const": true }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } }, "merged_into": { "description": "Set when the contractor merged this client into an existing one (a possible existing customer): that client now holds its leads, projects and external refs (and gets client.updated with updated_fields `merged`). Re-point your records to it instead of deleting them. null for an ordinary delete.", "anyOf": [ { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, { "type": "null" } ] } }, "required": [ "id", "object", "deleted", "external_refs" ] }, "ClientUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "client.updated" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Client" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "ConnectLink": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cl_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "connect_link" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "bound_organization": { "anyOf": [ { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, { "type": "null" } ] }, "client_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "redirect_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "consumed", "expired", "revoked" ] }, "grant": { "anyOf": [ { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "expires_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "consumed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The link to send to the contractor. Returned only when created.", "type": "string" } }, "required": [ "id", "object", "scopes", "bound_organization", "client_label", "external_reference", "metadata", "redirect_uri", "status", "grant", "created_at", "expires_at", "consumed_at" ] }, "ConnectLinkList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectLink" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "ConsentInput": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sms": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "marketing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "text": { "description": "The exact consent wording the person agreed to.", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "captured_at": { "anyOf": [ { "description": "RFC 3339 date-time with offset.", "type": "string", "format": "date-time" }, { "type": "null" } ] }, "method": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "additionalProperties": {} }, "CreateConnectLinkRequest": { "type": "object", "properties": { "scopes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "organization": { "description": "Bind the link to one organization (when you already know its id).", "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "client_label": { "description": "Required for unbound links: who you are connecting (shown to you on confirmation).", "type": "string", "minLength": 1, "maxLength": 120 }, "external_reference": { "type": "string", "minLength": 1, "maxLength": 255 }, "metadata": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "redirect_uri": { "description": "https URL on your verified domain to return to after consent. Light AI appends `connect_link` (cl_…), `grant` (grant_…), `organization` (org_…) and `grant_status` (`active`, or `pending` when an unbound link still needs POST /v1/partner/grants/{grant_id}/confirm); your own query parameters are kept, so one redirect_uri can serve every contractor.", "type": "string", "maxLength": 2048 }, "expires_in_hours": { "description": "Default 168 (7 days).", "type": "integer", "minimum": 1, "maximum": 168 } }, "required": [ "scopes" ], "additionalProperties": false }, "CreateLead200Response": { "anyOf": [ { "$ref": "#/components/schemas/LeadTouch" }, { "$ref": "#/components/schemas/Lead" } ] }, "CreateLeadRequest": { "type": "object", "properties": { "source": { "description": "Where the request came from.", "type": "string", "enum": [ "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other" ] }, "source_detail": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "external_ref": { "description": "Your id for this request. Retrying with the same ref returns the original lead.", "anyOf": [ { "$ref": "#/components/schemas/ExternalRefInput" }, { "type": "null" } ] }, "contact": { "description": "A name, and an email or a phone. null or \"\" in an optional field is the same as leaving it out.", "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "email": { "description": "Normalized when valid. An address that is not a valid email is kept as contact.email_raw when the phone works.", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "description": "Any common format; normalized to E.164. A number that cannot be normalized is kept as phone_raw when the email works.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "phone_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "address": { "description": "Optional. A lead without a street address is stored (a partial address as a hint) and becomes a project when one is added.", "anyOf": [ { "$ref": "#/components/schemas/AddressInput" }, { "type": "null" } ] }, "service_interest": { "description": "One of christmas_lights, permanent_lighting, landscape_lighting, custom; other text is kept and filed as custom.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "attribution": { "description": "utm_*, gclid, campaign ids and similar.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "null" } ] }, "consent": { "anyOf": [ { "$ref": "#/components/schemas/ConsentInput" }, { "type": "null" } ] }, "custom_fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "null" } ] }, "submitted_at": { "anyOf": [ { "description": "RFC 3339 date-time with offset.", "type": "string", "format": "date-time" }, { "type": "null" } ] }, "is_test": { "description": "Live keys reject true (use a test key for test data).", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "source", "contact" ], "additionalProperties": false }, "CreateMockupGenerationRequest": { "type": "object", "properties": { "model": { "description": "Light AI Gen 3.0 (the only model).", "type": "string", "const": "light-ai-gen-3.0" }, "images": { "description": "Number of images, 1–4 (default 1). 5 credits each.", "type": "integer", "minimum": 1, "maximum": 4 }, "source": { "description": "Default: the project's front view with its guide lines.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "front_view" }, "front_view_id": { "description": "The project's front view (default: the first one with a photo). Its measured guide lines place the lights, as in the app.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "photo_url" }, "url": { "description": "A public https URL of the front photo (JPEG, PNG or WebP, at most 10 MB; no redirects).", "type": "string", "maxLength": 2048 } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "photo_upload" }, "upload_id": { "description": "A photo uploaded with POST /v1/projects/{project_id}/photo_uploads.", "type": "string", "pattern": "^upl_[0-9a-f]{32}$" } }, "required": [ "type", "upload_id" ], "additionalProperties": false } ] }, "features": { "description": "front_view only: the measured features to light (template line-item ids). Default: every feature measured on the view.", "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "style_preset": { "description": "A starting point for bulb colors and pattern: `classic_warm_white`, `cool_white`, `multicolor`, `candy_cane` (red and white, alternating) or `red_and_green` (alternating). bulb_colors and c9_pattern override it.", "type": "string", "enum": [ "classic_warm_white", "cool_white", "multicolor", "candy_cane", "red_and_green" ] }, "bulb_colors": { "description": "Bulb colors for C9 lines and mini-light areas, as in the app.", "type": "object", "properties": { "c9": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "Warm White", "Cool White", "Red", "Green", "Blue", "Multicolor", "Purple", "Orange", "Pink", "Yellow" ] } }, "mini": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "Warm White", "Cool White", "Red", "Green", "Blue", "Multicolor", "Purple", "Orange", "Pink", "Yellow" ] } } }, "additionalProperties": false }, "c9_pattern": { "type": "string", "enum": [ "all-same", "alternating", "double-alternating", "other" ] }, "c9_pattern_description": { "description": "With c9_pattern `other`: the pattern in words.", "type": "string", "minLength": 1, "maxLength": 200 }, "ambiance": { "description": "Ambiance toggles of the project's template, e.g. {\"snow\": true, \"fullMoon\": true} (default: the template's defaults).", "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "additionalProperties": { "type": "boolean" } }, "instructions": { "description": "Extra preferences in words (at most 500 characters), as in the app's prompt box.", "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "CreateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "description": "https only, port 443 or 8443, public host.", "example": "https://hooks.example.com/light-ai", "type": "string", "maxLength": 2048 }, "events": { "description": "Event types, or [\"*\"] for every type your scopes can read and the organization's plan delivers live. A live endpoint refuses a listed type its plan does not deliver (403 plan_upgrade_required naming the type). Only listed types are delivered: list api_key.expiring and webhook_endpoint.disabled (or use [\"*\"]) to receive those notices here; a ping reaches only the endpoint it is sent to.", "minItems": 1, "maxItems": 40, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled" ] }, { "type": "string", "const": "*" } ] } }, "description": { "type": "string", "maxLength": 500 }, "static_header": { "description": "A fixed header sent with every delivery (e.g. for n8n Header Auth). Stored encrypted; never shown again. It belongs to its URL: a request that changes url must send static_header again (or null to remove it), otherwise 422 at /static_header.", "type": "object", "properties": { "name": { "example": "X-N8N-Auth", "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,63}$" }, "value": { "description": "Visible ASCII (spaces allowed inside); surrounding whitespace is trimmed. Stored encrypted. Responses show only its last 4 characters, and only when it is at least 12 characters long.", "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[\\x21-\\x7e](?:[\\x20-\\x7e]*[\\x21-\\x7e])?$" } }, "required": [ "name", "value" ], "additionalProperties": false }, "exclude_own_origin": { "description": "Skip events caused by this key's own writes (loop prevention). Default false.", "type": "boolean" } }, "required": [ "url", "events" ], "additionalProperties": false }, "DeletedObject": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "object", "deleted" ] }, "EmptyRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "Event": { "oneOf": [ { "$ref": "#/components/schemas/LeadCreatedEvent" }, { "$ref": "#/components/schemas/LeadTouchedEvent" }, { "$ref": "#/components/schemas/LeadUpdatedEvent" }, { "$ref": "#/components/schemas/LeadMockupReadyEvent" }, { "$ref": "#/components/schemas/ClientCreatedEvent" }, { "$ref": "#/components/schemas/ClientUpdatedEvent" }, { "$ref": "#/components/schemas/ClientDeletedEvent" }, { "$ref": "#/components/schemas/ProjectCreatedEvent" }, { "$ref": "#/components/schemas/ProjectStageChangedEvent" }, { "$ref": "#/components/schemas/QuotePublishedEvent" }, { "$ref": "#/components/schemas/QuoteViewedEvent" }, { "$ref": "#/components/schemas/QuoteExternalLinkClickedEvent" }, { "$ref": "#/components/schemas/QuoteChangeRequestedEvent" }, { "$ref": "#/components/schemas/QuoteApprovedEvent" }, { "$ref": "#/components/schemas/QuoteDeclinedEvent" }, { "$ref": "#/components/schemas/QuoteExpiredEvent" }, { "$ref": "#/components/schemas/QuoteLinkDisabledEvent" }, { "$ref": "#/components/schemas/QuoteLinkEnabledEvent" }, { "$ref": "#/components/schemas/QuoteSupersededEvent" }, { "$ref": "#/components/schemas/MockupCompletedEvent" }, { "$ref": "#/components/schemas/MockupFailedEvent" }, { "$ref": "#/components/schemas/OrganizationEntitlementChangedEvent" }, { "$ref": "#/components/schemas/GrantCreatedEvent" }, { "$ref": "#/components/schemas/GrantRevokedEvent" }, { "$ref": "#/components/schemas/ApiKeyExpiringEvent" }, { "$ref": "#/components/schemas/WebhookEndpointDisabledEvent" }, { "$ref": "#/components/schemas/PingEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "lead.created": "#/components/schemas/LeadCreatedEvent", "lead.touched": "#/components/schemas/LeadTouchedEvent", "lead.updated": "#/components/schemas/LeadUpdatedEvent", "lead.mockup_ready": "#/components/schemas/LeadMockupReadyEvent", "client.created": "#/components/schemas/ClientCreatedEvent", "client.updated": "#/components/schemas/ClientUpdatedEvent", "client.deleted": "#/components/schemas/ClientDeletedEvent", "project.created": "#/components/schemas/ProjectCreatedEvent", "project.stage_changed": "#/components/schemas/ProjectStageChangedEvent", "quote.published": "#/components/schemas/QuotePublishedEvent", "quote.viewed": "#/components/schemas/QuoteViewedEvent", "quote.external_link_clicked": "#/components/schemas/QuoteExternalLinkClickedEvent", "quote.change_requested": "#/components/schemas/QuoteChangeRequestedEvent", "quote.approved": "#/components/schemas/QuoteApprovedEvent", "quote.declined": "#/components/schemas/QuoteDeclinedEvent", "quote.expired": "#/components/schemas/QuoteExpiredEvent", "quote.link_disabled": "#/components/schemas/QuoteLinkDisabledEvent", "quote.link_enabled": "#/components/schemas/QuoteLinkEnabledEvent", "quote.superseded": "#/components/schemas/QuoteSupersededEvent", "mockup.completed": "#/components/schemas/MockupCompletedEvent", "mockup.failed": "#/components/schemas/MockupFailedEvent", "organization.entitlement_changed": "#/components/schemas/OrganizationEntitlementChangedEvent", "grant.created": "#/components/schemas/GrantCreatedEvent", "grant.revoked": "#/components/schemas/GrantRevokedEvent", "api_key.expiring": "#/components/schemas/ApiKeyExpiringEvent", "webhook_endpoint.disabled": "#/components/schemas/WebhookEndpointDisabledEvent", "ping": "#/components/schemas/PingEvent" } } }, "EventList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "ExternalRef": { "type": "object", "properties": { "system": { "type": "string" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "owner": { "description": "`self`: written by your integration (editable); others are read-only.", "type": "string", "enum": [ "self", "organization", "partner" ] }, "read_only": { "type": "boolean" } }, "required": [ "system", "namespace", "id", "owner", "read_only" ] }, "ExternalRefInput": { "type": "object", "properties": { "system": { "description": "Lowercase system name, e.g. `jobber`, `hubspot`, `highlevel`.", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, "namespace": { "description": "Optional sub-namespace in that system (e.g. an account id). null or \"\": none.", "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "system", "id" ], "additionalProperties": false }, "ExternalRefList": { "type": "object", "properties": { "object": { "type": "string", "const": "external_refs" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } }, "required": [ "object", "data" ] }, "ExternalRefValue": { "type": "object", "properties": { "system": { "type": "string" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" } }, "required": [ "system", "id" ] }, "Form": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^form_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "form" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "service_type": { "type": "string", "enum": [ "christmas_lights", "custom" ] }, "public_id": { "description": "The id in the install snippet (`ec_…`).", "type": "string" }, "install": { "type": "object", "properties": { "script": { "description": "The snippet to paste on the website.", "type": "string" }, "iframe_url": { "type": "string" }, "hosted_url": { "description": "Top-level page link (null unless the hosted page is on).", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "script", "iframe_url", "hosted_url" ] }, "domains": { "description": "Websites allowed to show the form (origins; `https://*.example.com` wildcards).", "type": "array", "items": { "type": "string" } }, "hosted_page_enabled": { "type": "boolean" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "photo": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "consent": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "questions": { "description": "In the order the form asks them (the owner can drag questions in the editor; follow-ups always come right after their parent question). The fixed address & photo card follows `surfaces` and `primary_color`, then contact details; the request is sent from the last question.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "prompt": { "type": "string" }, "type": { "type": "string", "enum": [ "color", "choice", "multi_choice", "toggle", "text" ] }, "enabled": { "type": "boolean" }, "required": { "type": "boolean" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "fullWidth": { "description": "Shown across the whole row when it starts one (e.g. ASAP).", "type": "boolean" }, "availableUntil": { "description": "The last day of the year it can be picked (recurring, the contractor's timezone); afterwards the form greys it out and a submitted pick is refused. Example: October until { month: 10, day: 31 }.", "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "month", "day" ] } }, "required": [ "value", "label" ] } } }, "required": [ "key", "prompt", "type", "enabled", "required", "choices" ] } }, "mockup_reveal": { "description": "How the request's AI mockup appears on the form (it starts on the homeowner's photo): `slider` (default, a draggable before/after divider), `flicker`, `day_night`, `bloom`, `sweep` or `curtain`; `slider_after` hands the five other styles over to the slider when they end. The form's own choice, else the company default. Set in the app.", "example": { "style": "slider", "slider_after": true }, "type": "object", "properties": { "style": { "type": "string", "enum": [ "slider", "flicker", "day_night", "bloom", "sweep", "curtain" ] }, "slider_after": { "type": "boolean" } }, "required": [ "style", "slider_after" ] }, "copy": { "type": "object", "properties": { "heading": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subheading": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "button_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "success_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "heading", "subheading", "button_label", "success_message" ] }, "instant_preview": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "images_per_lead": { "description": "AI mockup previews per request: always 1 (one AI mockup per request since October 2026). Kept for compatibility: PATCH still accepts 1 or 2 and stores 1.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_per_image": { "description": "Always 5.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "monthly_credit_cap": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "used_this_month": { "description": "Credits used or held by previews this UTC month.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "enabled", "images_per_lead", "credits_per_image", "monthly_credit_cap", "used_this_month" ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" } }, "required": [ "id", "object", "name", "status", "service_type", "public_id", "install", "domains", "hosted_page_enabled", "fields", "photo", "consent", "questions", "copy", "instant_preview", "created_at", "updated_at" ] }, "FormList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Grant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "grant" }, "status": { "type": "string", "enum": [ "pending", "active", "superseded", "revoked", "suspended", "expired" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "client_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "confirmed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "pending_expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "partner": { "type": "null" } }, "required": [ "id", "object", "status", "version", "scopes", "external_reference", "metadata", "client_label", "granted_at", "confirmed_at", "pending_expires_at", "revoked_at", "organization" ] }, "GrantCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "grant.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/GrantLifecycle" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "GrantLifecycle": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "grant" }, "status": { "type": "string", "enum": [ "pending", "active", "superseded", "revoked", "suspended", "expired" ] }, "organization_id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "organization_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "client_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "replaces_grant_id": { "description": "On grant.created with status `active`: the grant this one replaces for the same contractor (a re-consent with new scopes supersedes the earlier grant, which stops working now). Re-map that contractor to this grant id instead of provisioning it again; null for a first connection.", "anyOf": [ { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, { "type": "null" } ] } }, "required": [ "id", "object", "status", "organization_id", "external_reference" ] }, "GrantList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Grant" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "GrantRevokedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "grant.revoked" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/GrantLifecycle" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "lead" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "status": { "type": "string", "enum": [ "new", "converted", "spam", "archived", "duplicate" ] }, "held": { "description": "Accepted while the organization was paused; converts automatically on resume.", "type": "boolean" }, "needs_address": { "description": "A lead without a street address (none, or only a ZIP, city or region) waits for one (PATCH /v1/leads/{id} with address).", "type": "boolean" }, "source": { "type": "string", "enum": [ "website_widget", "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other", "manual" ] }, "source_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "$ref": "#/components/schemas/LeadContact" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "service_interest": { "anyOf": [ { "type": "string", "enum": [ "christmas_lights", "permanent_lighting", "landscape_lighting", "custom" ] }, { "type": "null" } ] }, "service_interest_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "consent": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "custom_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "client_id": { "anyOf": [ { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, { "type": "null" } ] }, "property_id": { "anyOf": [ { "type": "string", "pattern": "^prop_[0-9a-f]{32}$" }, { "type": "null" } ] }, "possible_client_match": { "description": "An existing client with the same email or phone that this integration was not allowed to update.", "anyOf": [ { "type": "object", "properties": { "client_id": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" } }, "required": [ "client_id" ] }, { "type": "null" } ] }, "project": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" }, "status": { "type": "string", "enum": [ "intake", "measuring", "mockup", "quote", "approved", "completed", "archived" ] }, "pipeline_stage": { "anyOf": [ { "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] }, { "type": "null" } ] }, "app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "pipeline_stage", "app_url" ] }, { "type": "null" } ] }, "form": { "description": "The website request form a website_widget lead came from (null for other sources).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^form_[0-9a-f]{32}$" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "mockup_status": { "description": "Instant preview of a website lead: not_requested (the form has no preview), pending (generating), ready (at least one image), failed, or skipped (a fallback applied: low credits, a cap, Off-Season, pause, plan). lead.mockup_ready fires once when it leaves pending.", "type": "string", "enum": [ "not_requested", "pending", "ready", "failed", "skipped" ] }, "form_answers": { "description": "Every website request form answer in the form's question order, with its question, group, raw value (the same value as custom_fields[key]) and display labels. Branch questions appear only when they were shown (e.g. tree_count only when trees_bushes is true). Answers to questions the form no longer has come last. An empty array for other sources.", "type": "array", "items": { "$ref": "#/components/schemas/LeadFormAnswer" } }, "preview_looks": { "description": "The look (light color value, e.g. `warm_white`) of the request's instant preview: an array with at most one item (one AI mockup per request; leads sent before October 2026 may list up to 3, in order). Empty when there is no preview.", "example": [ "warm_white" ], "type": "array", "items": { "type": "string" } }, "offer": { "description": "The website request form's offer (for example \"Black Friday: 20% off installs\") that was showing when the homeowner sent the request, kept as it was then; null when no offer was active and for other sources. `label` is \"20% off\", \"$150 off\" or empty (a headline-only offer). When the request becomes a project, the quote builder pre-fills the quote discount from it once (the contractor can change or remove it); the published quote shows it as `discount` with a `label` such as \"Black Friday offer\".", "example": { "template": "black_friday", "headline": "Black Friday: 20% off installs", "discount_type": "percent", "discount_percent": 20, "discount_amount": null, "label": "20% off", "ends_at": "2026-11-30T05:59:00Z", "book_by": "Book by Dec 1 for install before Christmas", "captured_at": "2026-11-27T14:03:11Z" }, "anyOf": [ { "type": "object", "properties": { "template": { "description": "The Light AI campaign template that filled the offer; null or absent for the contractor's own.", "anyOf": [ { "type": "string", "enum": [ "classic", "early_bird", "black_friday", "last_chance" ] }, { "type": "null" } ] }, "headline": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percent", "amount" ] }, "discount_percent": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discount_amount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "label": { "type": "string" }, "ends_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "book_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "headline", "discount_type", "discount_percent", "discount_amount", "label", "ends_at", "book_by", "captured_at" ] }, { "type": "null" } ] }, "assets": { "description": "The homeowner's photo and the instant preview images (each with its `look`). GET, list and search answers carry 60-minute signed URLs; webhook payloads and the events feed carry the ids with url null (fetch the lead for fresh links).", "type": "object", "properties": { "photos": { "type": "array", "items": { "$ref": "#/components/schemas/LeadAsset" } }, "mockups": { "type": "array", "items": { "$ref": "#/components/schemas/LeadPreviewAsset" } } }, "required": [ "photos", "mockups" ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } }, "touch_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_touched_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "submitted_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "replayed": { "description": "Present when an external_ref replay returned an existing lead.", "type": "boolean", "const": true }, "fixture": { "description": "Test-mode fixture object.", "type": "boolean", "const": true } }, "required": [ "id", "object", "livemode", "status", "held", "needs_address", "source", "source_detail", "contact", "address", "service_interest", "service_interest_raw", "message", "attribution", "consent", "custom_fields", "notes", "status_reason", "client_id", "property_id", "possible_client_match", "project", "external_refs", "touch_count", "last_touched_at", "submitted_at", "created_at", "updated_at" ] }, "LeadAsset": { "type": "object", "properties": { "id": { "description": "Asset id (`lph_…` photo, `mk_…` preview image).", "type": "string" }, "url": { "description": "Signed HTTPS URL valid for 60 minutes (null in webhook payloads, or when the image was removed).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "url", "expires_at" ] }, "LeadContact": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email_raw": { "description": "The address as received when it is not a valid email (the lead was kept because its phone works).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "E.164, or null when the number could not be normalized (see phone_raw).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone_raw": { "description": "The number as received (extensions, local or foreign formats are kept here).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "first_name", "last_name", "email", "phone", "phone_raw", "phone_verified" ] }, "LeadCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "lead.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Lead" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "LeadFormAnswer": { "type": "object", "properties": { "key": { "description": "Stable answer key, the same key as in custom_fields (e.g. `surfaces`, `primary_color`, `tree_count`, `custom_…`).", "example": "surfaces", "type": "string" }, "question": { "description": "The question as the form asked it (the key when the form no longer has that question).", "example": "What should we light?", "type": "string" }, "group": { "description": "Answer group: `lighting`, `trees` (trees & bushes), `decor` (wreaths & garland), `details` or `custom` (the contractor's own questions). More groups may be added.", "example": "lighting", "type": "string" }, "type": { "description": "Question type (null when the form no longer has the question).", "example": "multi_choice", "anyOf": [ { "type": "string", "enum": [ "color", "choice", "multi_choice", "toggle", "text" ] }, { "type": "null" } ] }, "value": { "description": "The raw answer, identical to custom_fields[key]: a choice value, an array of values, true/false or text.", "example": [ "eaves", "garage" ] }, "labels": { "description": "Display labels of the answer in order (toggles: `Yes` or `No`; text: the text).", "example": [ "Roof peaks + gutters", "Garage doors" ], "type": "array", "items": { "type": "string" } } }, "required": [ "key", "question", "group", "type", "value", "labels" ] }, "LeadList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "LeadMockupReadyEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "lead.mockup_ready" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Lead" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "LeadPreviewAsset": { "type": "object", "properties": { "id": { "description": "Asset id (`lph_…` photo, `mk_…` preview image).", "type": "string" }, "url": { "description": "Signed HTTPS URL valid for 60 minutes (null in webhook payloads, or when the image was removed).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "look": { "description": "The look (light color) of this preview image: `warm_white`, `cool_white`, `multi`, `candy_cane`, `red_green`, `red_white_green`, `red`, `green`, `blue` or `blue_white` (more may be added). The preview uses the color the homeowner picked (one per request; older leads may have up to 3). Null when unknown.", "example": "warm_white", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "url", "expires_at" ] }, "LeadTouch": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "lead_touch" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "lead_id": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" }, "source": { "type": "string", "enum": [ "website_widget", "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other", "manual" ] }, "source_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "consent": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "custom_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] }, "submitted_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "replayed": { "type": "boolean", "const": true } }, "required": [ "id", "object", "lead_id", "source", "source_detail", "contact", "message", "attribution", "consent", "custom_fields", "external_ref", "submitted_at", "created_at" ] }, "LeadTouchedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "lead.touched" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Lead" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "touch": { "$ref": "#/components/schemas/LeadTouch" } }, "required": [ "object", "previous_attributes", "touch" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "LeadTouchList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadTouch" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "LeadUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "lead.updated" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Lead" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "LineItem": { "type": "object", "properties": { "id": { "type": "string" }, "item_key": { "description": "The line item id in the published document.", "type": "string" }, "code": { "description": "Stable catalog code (template line item); null for custom lines.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "measurement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "description": "The measured quantity (decimal for feet and square feet, whole for counted items); null for an unmeasured line.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "enum": [ "ft", "sqft", "each", "set" ] }, { "type": "null" } ] }, "unit_price": { "description": "Set when quantity × unit_price equals amount to the cent; otherwise null (e.g. mini lights priced by the set) and amount is the line total.", "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "unit_price_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "amount": { "$ref": "#/components/schemas/Money" }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "bulb": { "anyOf": [ { "type": "string", "enum": [ "c9", "mini" ] }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "type": "string" } }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" }, "selected": { "type": "boolean" }, "taxable": { "type": "null" } }, "required": [ "id", "item_key", "code", "name", "description", "measurement", "quantity", "unit", "unit_price", "unit_price_cents", "amount", "total_cents", "bulb", "colors", "pattern", "required", "selected", "taxable" ] }, "MarkApprovedRequest": { "type": "object", "properties": { "approved_at": { "anyOf": [ { "description": "RFC 3339 date-time with offset.", "type": "string", "format": "date-time" }, { "type": "null" } ] }, "selected_item_ids": { "description": "Defaults to the published selection.", "anyOf": [ { "minItems": 1, "maxItems": 300, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "type": "null" } ] }, "external_ref": { "description": "The approval's id in your system (e.g. the Jobber quote id).", "anyOf": [ { "$ref": "#/components/schemas/ExternalRefInput" }, { "type": "null" } ] }, "signed_by": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "MarkDeclinedRequest": { "type": "object", "properties": { "declined_at": { "anyOf": [ { "description": "RFC 3339 date-time with offset.", "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefInput" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "MockupCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "mockup.completed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/MockupGeneration" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "MockupFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "mockup.failed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/MockupGeneration" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "MockupGeneration": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^mgen_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "mockup_generation" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "status": { "description": "`succeeded` when at least one image succeeded (each image has its own status), `failed` when none did. Every failed image is refunded.", "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" }, { "type": "null" } ] }, "model": { "type": "string", "const": "light-ai-gen-3.0" }, "model_name": { "type": "string" }, "images_requested": { "type": "integer", "minimum": 1, "maximum": 4 }, "images_succeeded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "images_failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "front_view", "photo_url", "photo_upload" ] }, "front_view_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type" ] }, "options": { "description": "The options the generation used (preset, bulb colors, pattern, ambiance, features, instructions).", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "credits": { "type": "object", "properties": { "per_image": { "description": "Credits per image (5, as in the app).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reserved": { "description": "Held for images still generating.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "charged": { "description": "Spent on succeeded images.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "refunded": { "description": "Returned for failed images.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "per_image", "reserved", "charged", "refunded" ] }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/MockupImage" } }, "failure_code": { "anyOf": [ { "type": "string", "enum": [ "generation_failed", "generation_paused", "generation_interrupted", "generation_unavailable", "queue_timeout", "source_photo_unavailable", "project_deleted" ] }, { "type": "null" } ] }, "generated_via": { "description": "The requester label in the contractor's credit and project history: \"Generated via API by \" or \"Generated via API key \"\"\". The organization and the partner that made the request see it; any other partner sees \"Generated via API\".", "type": "string" }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "simulated": { "description": "Test mode only.", "type": "boolean" } }, "required": [ "id", "object", "livemode", "status", "project_id", "model", "model_name", "images_requested", "images_succeeded", "images_failed", "source", "options", "credits", "images", "failure_code", "generated_via", "created_at", "updated_at", "completed_at" ] }, "MockupImage": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 1, "maximum": 4 }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "mockup_id": { "description": "The mockup in the project's mockup history (`mk_…`), once succeeded.", "anyOf": [ { "type": "string", "pattern": "^mk_[0-9a-f]{32}$" }, { "type": "null" } ] }, "url": { "description": "Signed image URL (WebP), valid until expires_at. null in webhook payloads: GET the generation for a fresh URL.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "removed": { "description": "true when the image was generated but has since been deleted from the project.", "type": "boolean" }, "failure_code": { "description": "`generation_failed` (the image could not be generated), `generation_paused` (too many recent failures or too much at once for this account: retry in a few minutes), `generation_interrupted`, `generation_unavailable`, `queue_timeout` (the image could not be started within 6 hours: request it again), `source_photo_unavailable`, `project_deleted`. A failed image is always refunded.", "anyOf": [ { "type": "string", "enum": [ "generation_failed", "generation_paused", "generation_interrupted", "generation_unavailable", "queue_timeout", "source_photo_unavailable", "project_deleted" ] }, { "type": "null" } ] }, "sample": { "description": "Test mode: a fixed sample image, nothing was generated.", "type": "boolean" } }, "required": [ "index", "status", "mockup_id", "url", "expires_at", "removed", "failure_code" ] }, "Money": { "type": "object", "properties": { "cents": { "description": "Integer amount in cents (the source of truth).", "example": 245000, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "decimal": { "description": "The same amount as a decimal string.", "example": "2450.00", "type": "string" }, "currency": { "type": "string", "const": "USD" } }, "required": [ "cents", "decimal", "currency" ] }, "MoveStageRequest": { "type": "object", "properties": { "expected_stage": { "description": "The stage you believe the project is in (409 stale_state otherwise).", "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] }, "stage": { "description": "A display stage. `approved` is reserved for an actual approval (mark_approved).", "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "completed", "closed_lost" ] }, "reason": { "description": "null or \"\": none.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "required": [ "expected_stage", "stage" ], "additionalProperties": false }, "OrganizationEntitlementChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "organization.entitlement_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/OrganizationEntitlements" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "OrganizationEntitlements": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "organization_entitlements" }, "entitlements": { "type": "object", "properties": { "tier": { "type": "string" }, "paused": { "type": "boolean" }, "live_api": { "type": "boolean" }, "live_inbound": { "type": "boolean" }, "live_webhooks": { "type": "boolean" }, "quote_events": { "type": "boolean" }, "engagement": { "type": "boolean" }, "test_mode": { "type": "boolean" } }, "required": [ "tier", "paused" ] }, "api_disabled": { "type": "boolean" }, "off_season": { "description": "Off-Season phase in effect: `none`, `scheduled` (starts later), `active` or `returning`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "object", "entitlements", "api_disabled", "off_season" ] }, "PartnerUpdateGrantRequest": { "type": "object", "properties": { "external_reference": { "description": "Your id for this contractor (e.g. a HighLevel locationId). null or \"\" clears it.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "metadata": { "description": "Replaces the metadata; null is absent (send {} to empty it).", "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, { "type": "null" } ] } }, "additionalProperties": false }, "PhotoUpload": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^upl_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "photo_upload" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "project_id": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" }, "upload_url": { "description": "PUT the photo bytes here (Content-Type image/jpeg, image/png or image/webp, at most 10 MB). null in test mode.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "method": { "type": "string", "const": "PUT" }, "max_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_types": { "type": "array", "items": { "type": "string" } }, "expires_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" } }, "required": [ "id", "object", "livemode", "project_id", "upload_url", "method", "max_bytes", "content_types", "expires_at" ] }, "PingEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "ping" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/PingObject" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "PingObject": { "type": "object", "properties": {} }, "PipelineStage": { "type": "object", "properties": { "object": { "type": "string", "const": "pipeline_stage" }, "id": { "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] }, "project_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "value": { "description": "Total value; null without quotes:read.", "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "object", "id", "project_count", "value" ] }, "PipelineStageList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Principal": { "type": "object", "properties": { "object": { "type": "string", "const": "principal" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f]{32}$" }, "name": { "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "expires_in_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replaced_by": { "anyOf": [ { "type": "string", "pattern": "^key_[0-9a-f]{32}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "livemode", "scopes", "expires_at", "expires_in_days", "replaced_by" ] }, "partner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ptr_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "partner" }, "legal_name": { "type": "string" }, "display_name": { "type": "string" }, "verified_domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "active_grants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "object", "legal_name", "display_name", "verified_domain", "status", "verified", "active_grants" ] }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" } }, "required": [ "id", "name", "timezone", "paused" ] }, { "type": "null" } ] }, "grant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "id", "scopes", "external_reference", "metadata" ] }, { "type": "null" } ] }, "scopes": { "description": "Effective scopes: key ∩ grant ∩ the organization's plan.", "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "entitlements": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "reads_per_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "writes_per_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lead_daily_cap": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "reads_per_minute", "writes_per_minute", "lead_daily_cap" ] }, "api_version": { "type": "string" } }, "required": [ "object", "livemode", "key", "partner", "organization", "grant", "scopes", "entitlements", "limits", "api_version" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "description": "Stable machine-readable error code.", "type": "string" }, "doc_url": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "pointer", "detail" ] } } }, "required": [ "type", "title", "status", "detail", "instance", "code", "doc_url", "request_id" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "project" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "intake", "measuring", "mockup", "quote", "approved", "completed", "archived" ] }, "pipeline_stage": { "description": "The pipeline column; null for an archived project.", "anyOf": [ { "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] }, { "type": "null" } ] }, "client_id": { "anyOf": [ { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, { "type": "null" } ] }, "property_id": { "anyOf": [ { "type": "string", "pattern": "^prop_[0-9a-f]{32}$" }, { "type": "null" } ] }, "lead": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" }, "source": { "anyOf": [ { "type": "string", "enum": [ "website_widget", "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other", "manual" ] }, { "type": "null" } ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } }, "required": [ "id", "source", "external_refs" ] }, { "type": "null" } ] }, "assigned_rep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "lighting_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "current_quote_id": { "anyOf": [ { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "request_offer": { "description": "The offer of the website request this project came from, as the request kept it (the same object as lead.offer); null otherwise. The quote builder pre-fills the quote discount from it once; the published quote shows it as `discount.label`.", "example": { "template": "black_friday", "headline": "Black Friday: 20% off installs", "discount_type": "percent", "discount_percent": 20, "discount_amount": null, "label": "20% off", "ends_at": "2026-11-30T05:59:00Z", "book_by": "Book by Dec 1 for install before Christmas", "captured_at": "2026-11-27T14:03:11Z" }, "anyOf": [ { "type": "object", "properties": { "template": { "description": "The Light AI campaign template that filled the offer; null or absent for the contractor's own.", "anyOf": [ { "type": "string", "enum": [ "classic", "early_bird", "black_friday", "last_chance" ] }, { "type": "null" } ] }, "headline": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percent", "amount" ] }, "discount_percent": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discount_amount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "label": { "type": "string" }, "ends_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "book_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "headline", "discount_type", "discount_percent", "discount_amount", "label", "ends_at", "book_by", "captured_at" ] }, { "type": "null" } ] }, "estimated_value": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } }, "app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "Last change of the project or of what the API derives for it (pipeline_stage, current_quote_id): updated_since sees a decline or a republish.", "type": "string" }, "fixture": { "type": "boolean", "const": true } }, "required": [ "id", "object", "livemode", "name", "status", "pipeline_stage", "client_id", "property_id", "lead", "assigned_rep", "lighting_type", "notes", "current_quote_id", "estimated_value", "external_refs", "app_url", "created_at", "updated_at" ] }, "ProjectCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "project.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Project" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "ProjectList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "ProjectStageChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "project.stage_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Project" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "stage_change": { "$ref": "#/components/schemas/StageChange" } }, "required": [ "object", "previous_attributes", "stage_change" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "Property": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prop_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "property" }, "client_id": { "anyOf": [ { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, { "type": "null" } ] }, "is_primary": { "type": "boolean" }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" } }, "required": [ "id", "object", "client_id", "is_primary", "property_type", "address", "created_at", "updated_at" ] }, "PropertyList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Property" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "PropertyReference": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prop_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "property" } }, "required": [ "id", "object" ] }, "PutExternalRefRequest": { "type": "object", "properties": { "id": { "description": "The object's id in that system.", "type": "string", "minLength": 1, "maxLength": 255 }, "namespace": { "description": "Optional sub-namespace in that system. null or \"\": none.", "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "quote" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "status": { "type": "string", "enum": [ "sent", "approved", "declined", "expired", "superseded", "disabled" ] }, "is_current": { "type": "boolean" }, "superseded_by": { "anyOf": [ { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "replaces_quote_id": { "anyOf": [ { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "external_refs": { "description": "The ids integrations wrote back on this quote (PUT /v1/quotes/{id}/external_refs/{system}).", "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } }, "truncated": { "description": "Webhook payloads only: present (true) when the quote was too large for one delivery (256 KB). line_items is then empty; read the full quote with GET /v1/quotes/{id}. Never present on API responses.", "type": "boolean", "const": true }, "project": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prj_[0-9a-f]{32}$" }, "pipeline_stage": { "anyOf": [ { "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost" ] }, { "type": "null" } ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } }, "required": [ "id", "pipeline_stage", "external_refs" ] }, "lead": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lead_[0-9a-f]{32}$" }, "source": { "anyOf": [ { "type": "string", "enum": [ "website_widget", "api", "google_ads_lead_form", "google_lsa", "meta_lead_ad", "highlevel", "hubspot", "jobber", "service_autopilot", "realgreen", "sweepandgo", "deeplawn", "zapier", "n8n", "make", "crm_import", "other", "manual" ] }, { "type": "null" } ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } }, "required": [ "id", "source", "external_refs" ] }, { "type": "null" } ] }, "client": { "description": "Contact details need clients:read; otherwise only the id.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cli_[0-9a-f]{32}$" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "E.164, or null when the stored number could not be normalized (see phone_raw).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone_raw": { "description": "The number as stored in Light AI.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } }, "required": [ "id" ] }, { "type": "null" } ] }, "property": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^prop_[0-9a-f]{32}$" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] } }, "required": [ "id" ] }, { "type": "null" } ] }, "assigned_rep": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "terms": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disclaimer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revision": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rev_[0-9a-f]{32}$" }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "published_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "evidence_hash": { "type": "string" } }, "required": [ "id", "number", "published_at", "evidence_hash" ] }, "approval_mode": { "anyOf": [ { "type": "string", "enum": [ "light-ai", "external", "view-only" ] }, { "type": "null" } ] }, "allow_selections": { "type": "boolean" }, "currency": { "type": "string", "const": "USD" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, "discount": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "number" }, "label": { "description": "The discount line's name on the customer quote, e.g. \"Black Friday offer\" (a website request's offer); absent for a plain discount.", "type": "string" } }, "required": [ "type", "value" ] }, { "type": "null" } ] }, "totals": { "type": "object", "properties": { "subtotal": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "tax": { "type": "null" }, "total": { "$ref": "#/components/schemas/Money" }, "deposit": { "type": "object", "properties": { "percentage": { "type": "number" }, "amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "percentage", "amount" ] } }, "required": [ "subtotal", "discount", "tax", "total", "deposit" ] }, "selected_item_ids": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "properties": { "customer_url": { "description": "The homeowner's quote link. Only with the opt-in quotes:share_link scope; every read is audited.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdf": { "description": "Present only when a PDF is bound to this exact revision.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "id", "sha256" ] }, { "type": "null" } ] }, "assets_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "customer_url", "app_url", "external_url", "external_label", "pdf" ] }, "assets": { "type": "object", "properties": { "mockups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "description": "The image's title as published on the quote. For a mockup: the image's own title, else its mockup card's name (cards are named from their light colors, for example \"Warm White\" or \"Candy Cane\", unless the contractor renamed them).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "description": "null (ids only) unless the credential or endpoint holds quotes:asset_links: then a durable link that works while the customer link is active (at most 30 days); null for an image no longer stored.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "url" ] } }, "schematics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "description": "The image's title as published on the quote. For a mockup: the image's own title, else its mockup card's name (cards are named from their light colors, for example \"Warm White\" or \"Candy Cane\", unless the contractor renamed them).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "description": "null (ids only) unless the credential or endpoint holds quotes:asset_links: then a durable link that works while the customer link is active (at most 30 days); null for an image no longer stored.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "url" ] } } }, "required": [ "mockups", "schematics" ] }, "engagement": { "type": "object", "properties": { "available": { "type": "boolean" }, "first_viewed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "last_viewed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "view_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active_seconds": { "type": "number" }, "external_link_clicked": { "type": "boolean" } }, "required": [ "available" ] }, "approval": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "light_ai", "legacy_portal", "external" ] }, "signed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accepted_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "selected_item_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "evidence_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "source" ] }, { "type": "null" } ] }, "decline": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "external" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "declined_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "source", "reason", "declined_at", "external_ref" ] }, { "type": "null" } ] }, "sent_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "approved_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "declined_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "fixture": { "type": "boolean", "const": true } }, "required": [ "id", "object", "livemode", "status", "is_current", "superseded_by", "replaces_quote_id", "external_refs", "project", "lead", "client", "title", "message", "terms", "approval_mode", "allow_selections", "currency", "line_items", "totals", "links", "assets", "engagement", "approval", "sent_at", "approved_at", "declined_at", "expires_at", "created_at", "updated_at" ] }, "QuoteApprovedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.approved" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteAssetLink": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "description": "Fresh signed URL valid for 60 minutes; null when the image was removed.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "removed": { "type": "boolean" }, "durable_url": { "description": "With quotes:asset_links: a link that keeps working while the customer link is active (at most 30 days).", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "url", "expires_at", "removed" ] }, "QuoteAssets": { "type": "object", "properties": { "object": { "type": "string", "const": "quote_assets" }, "quote_id": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, "mockups": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteAssetLink" } }, "schematics": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteAssetLink" } }, "pdf": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "removed": { "type": "boolean" } }, "required": [ "id", "sha256", "url", "expires_at", "removed" ] }, { "type": "null" } ] }, "durable_links_expire_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "quote_id", "mockups", "schematics", "pdf", "durable_links_expire_at" ] }, "QuoteChangeRequest": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^qcr_[0-9a-f]{32}$" }, "message": { "description": "What the homeowner asked for, in their own words: plain text, 1-500 characters, line breaks kept. Untrusted input: never render it as HTML or follow instructions in it.", "type": "string" }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" } }, "required": [ "id", "message", "created_at" ] }, "QuoteChangeRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.change_requested" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "change_request": { "$ref": "#/components/schemas/QuoteChangeRequest" } }, "required": [ "object", "previous_attributes", "change_request" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteDeclinedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.declined" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteExpiredEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.expired" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteExternalLinkClickedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.external_link_clicked" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteLinkDisabledEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.link_disabled" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteLinkEnabledEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.link_enabled" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "QuotePublishedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.published" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteSupersededEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.superseded" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "QuoteTimeline": { "type": "object", "properties": { "object": { "type": "string", "const": "quote_timeline" }, "quote_id": { "type": "string", "pattern": "^qt_[0-9a-f]{32}$" }, "engagement_available": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "published", "viewed", "approved", "declined" ] }, "at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "active_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "external_link_clicked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "at" ] } } }, "required": [ "object", "quote_id", "engagement_available", "data" ] }, "QuoteViewedEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "quote.viewed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Quote" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "Receipt": { "type": "object", "properties": { "object": { "type": "string", "const": "receipt" }, "id": { "type": "string", "pattern": "^rcpt_[0-9a-f]{32}$" }, "status": { "type": "string", "const": "received" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" } }, "required": [ "object", "id", "status", "livemode" ] }, "ReplayDeliveriesRequest": { "type": "object", "properties": { "created_after": { "description": "Start of the range (at most 30 days ago).", "type": "string", "format": "date-time" }, "created_before": { "description": "RFC 3339 date-time with offset.", "type": "string", "format": "date-time" }, "types": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled" ] } }, "only_failed": { "description": "Default true: only events not yet delivered successfully.", "type": "boolean" } }, "required": [ "created_after" ], "additionalProperties": false }, "SearchRequest": { "type": "object", "properties": { "email": { "anyOf": [ { "description": "An email address (\"\" or null: absent).", "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/AddressInput" }, { "type": "null" } ] } }, "additionalProperties": false }, "StageChange": { "type": "object", "properties": { "from": { "description": "The stage before this change.", "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost", "archived" ] }, "to": { "description": "The stage this change reached (`archived`: the project was archived).", "type": "string", "enum": [ "request", "quote_drafted", "quote_sent", "approved", "completed", "closed_lost", "archived" ] }, "sequence": { "description": "Increases by one with every stage change of the project: order transitions and drop duplicates by it.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "from", "to", "sequence" ] }, "TestHelperRequest": { "type": "object", "properties": { "document": { "description": "publish_quote only: a quote-website-v1 document to model the contractor's real line items.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, "UpdateClientRequest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "email": { "description": "null or \"\" clears the email.", "anyOf": [ { "format": "email", "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "description": "null or \"\" clears the phone.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "UpdateFormRequest": { "type": "object", "properties": { "expected_updated_at": { "description": "The form's updated_at you last read (409 stale_state otherwise).", "type": "string", "format": "date-time" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "domains": { "description": "Replaces the allowed websites (origins).", "maxItems": 25, "type": "array", "items": { "type": "string", "maxLength": 2048 } }, "copy": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 120 }, "subheading": { "type": "string", "minLength": 1, "maxLength": 300 }, "button_label": { "type": "string", "minLength": 1, "maxLength": 80 }, "success_message": { "type": "string", "minLength": 1, "maxLength": 300 } }, "additionalProperties": false }, "instant_preview": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "images_per_lead": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 } ] }, "monthly_credit_cap": { "type": "integer", "minimum": 5, "maximum": 5000 } }, "additionalProperties": false } }, "required": [ "expected_updated_at" ], "additionalProperties": false }, "UpdateLead200Response": { "anyOf": [ { "$ref": "#/components/schemas/Lead" }, { "$ref": "#/components/schemas/Receipt" } ] }, "UpdateLeadRequest": { "type": "object", "properties": { "status": { "description": "`archived` with reason `test` also archives the untouched intake project; `new` reopens a spam or archived lead.", "type": "string", "enum": [ "new", "archived", "spam" ] }, "notes": { "description": "null or \"\" clears the notes.", "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "reason": { "description": "null or \"\": none.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "address": { "description": "Adds the street address of a lead that has none yet (no address, or only a ZIP or city); a street address converts the lead.", "$ref": "#/components/schemas/AddressInput" }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "description": "https only, port 443 or 8443, public host.", "example": "https://hooks.example.com/light-ai", "type": "string", "maxLength": 2048 }, "events": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled" ] }, { "type": "string", "const": "*" } ] } }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "static_header": { "anyOf": [ { "description": "A fixed header sent with every delivery (e.g. for n8n Header Auth). Stored encrypted; never shown again. It belongs to its URL: a request that changes url must send static_header again (or null to remove it), otherwise 422 at /static_header.", "type": "object", "properties": { "name": { "example": "X-N8N-Auth", "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,63}$" }, "value": { "description": "Visible ASCII (spaces allowed inside); surrounding whitespace is trimmed. Stored encrypted. Responses show only its last 4 characters, and only when it is at least 12 characters long.", "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[\\x21-\\x7e](?:[\\x20-\\x7e]*[\\x21-\\x7e])?$" } }, "required": [ "name", "value" ], "additionalProperties": false }, { "type": "null" } ] }, "exclude_own_origin": { "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "additionalProperties": false }, "UpsertClient200Response": { "anyOf": [ { "$ref": "#/components/schemas/Client" }, { "$ref": "#/components/schemas/ClientReference" } ] }, "UpsertClientRequest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "email": { "anyOf": [ { "description": "An email address (\"\" or null: absent).", "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "description": "Adds this property when it is a street address (a line1, a formatted line that starts with the house number, or a place_id) new for the client. A partial address (only a ZIP, city or region, as CRMs send for most contacts) is ignored.", "anyOf": [ { "$ref": "#/components/schemas/AddressInput" }, { "type": "null" } ] }, "external_ref": { "description": "Matched first (your namespace only), then email, then phone.", "anyOf": [ { "$ref": "#/components/schemas/ExternalRefInput" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "description": "The system that caused this write (shown as origin.source_system on the resulting events, for loop prevention).", "example": "jobber", "type": "string", "pattern": "^[a-z0-9][a-z0-9_]{1,39}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whd_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "webhook_delivery" }, "event_id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled", "ping" ] }, { "type": "null" } ] }, "endpoint_id": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" }, "status": { "type": "string", "enum": [ "pending", "retrying", "leased", "succeeded", "abandoned", "cancelled" ] }, "cancel_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "replay": { "type": "boolean" }, "attempt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "last_status_code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "last_error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "attempts": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "attempted_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "status_code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "latency_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "attempted_at", "status_code", "latency_ms", "error_class", "response_excerpt", "request_headers" ] } }, { "type": "null" } ] } }, "required": [ "id", "object", "event_id", "event_type", "endpoint_id", "status", "cancel_reason", "replay", "attempt_count", "next_attempt_at", "last_status_code", "last_error_class", "created_at", "completed_at", "attempts" ] }, "WebhookDeliveryList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled", "ping" ] } }, "unentitled_events": { "description": "Subscribed types the organization's current plan does not deliver live (e.g. after a downgrade). They resume when the plan includes them.", "type": "array", "items": { "type": "string", "enum": [ "lead.created", "lead.touched", "lead.updated", "lead.mockup_ready", "client.created", "client.updated", "client.deleted", "project.created", "project.stage_changed", "quote.published", "quote.viewed", "quote.external_link_clicked", "quote.change_requested", "quote.approved", "quote.declined", "quote.expired", "quote.link_disabled", "quote.link_enabled", "quote.superseded", "mockup.completed", "mockup.failed", "organization.entitlement_changed", "grant.created", "grant.revoked", "api_key.expiring", "webhook_endpoint.disabled", "ping" ] } }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "disabled_by_system", "disabled_by_revocation", "suspended" ] }, "status_reason": { "description": "Why it is not enabled. `disabled_by_organization`: the contractor disabled it in Settings → Developers. Until they enable it there (it then returns to the state it had before their disable) or remove it there, the API cannot enable, re-point or delete it, nor create or point another endpoint at the same receiver (the same host, port and path; query string, case, repeated or trailing slashes and :443 ignored): each answers 409 stale_state with current_state `disabled_by_organization`. A partner's partner-level endpoints at that receiver receive none of that contractor's events meanwhile (its organization.entitlement_changed included; grant notices addressed to the partner still arrive). A different path or host is a different receiver. This stops deliveries, not access: a partner's key still reads through its grant (the contractor suspends or revokes the grant to stop the partner). `gone` / `circuit_breaker`: Light AI stopped it (410, or 72 hours of failures). `grant_suspended`, `grant_revoked`, key and security reasons: access was suspended or revoked.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabled_while_suspended": { "type": "boolean" }, "api_version": { "type": "string" }, "exclude_own_origin": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ] } }, "kind": { "type": "string", "enum": [ "organization", "partner" ] }, "grant_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" } }, { "type": "null" } ] }, "static_header": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "value_redacted": { "description": "`…` plus the last 4 characters of a value of 12 or more characters; `…` alone for a shorter value.", "type": "string" } }, "required": [ "name", "value_redacted" ] }, { "type": "null" } ] }, "created_by": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key", "user" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "partner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "id", "name" ] }, "lane": { "type": "string", "enum": [ "normal", "degraded" ] }, "backlog": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oldest_pending_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "last_success_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "last_failure_at": { "anyOf": [ { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "updated_at": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "secret": { "description": "The signing secret (whsec_…). Returned only when created, re-subscribed or rotated.", "type": "string" } }, "required": [ "id", "object", "url", "description", "events", "unentitled_events", "livemode", "status", "status_reason", "disabled_while_suspended", "api_version", "exclude_own_origin", "scopes", "kind", "grant_ids", "static_header", "created_by", "lane", "backlog", "oldest_pending_at", "last_success_at", "last_failure_at", "created_at", "updated_at" ] }, "WebhookEndpointDisabledEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "created": { "format": "date-time", "description": "RFC 3339 timestamp (UTC, milliseconds).", "type": "string" }, "livemode": { "description": "false for objects created with a test key.", "type": "boolean" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9a-f]{32}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "grant": { "description": "Partner deliveries carry the grant (with your external_reference for routing).", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^grant_[0-9a-f]{32}$" }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "external_reference", "metadata" ] }, { "type": "null" } ] }, "origin": { "description": "What caused this event (the immediate actor, never inherited from an earlier event).", "type": "object", "properties": { "type": { "description": "Who caused the event: `app` a member in Light AI (principal_id `usr_…`), `embed` the website lead form, `portal` the homeowner on the quote page (views, link clicks, approvals), `api` an API key (principal_id `key_…`), `inbound` an inbound lead source (principal_id `src_…`), `system` Light AI itself (expiry sweep, reconciliation, plan changes, endpoint health).", "type": "string", "enum": [ "app", "embed", "portal", "api", "inbound", "system" ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_system": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_ref": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRefValue" }, { "type": "null" } ] } }, "required": [ "type", "principal_id" ] }, "type": { "type": "string", "const": "webhook_endpoint.disabled" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/WebhookEndpointDisabledNotice" }, "previous_attributes": { "description": "For *.updated and state changes: the changed fields' values before the change.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "object", "previous_attributes" ] } }, "required": [ "id", "object", "api_version", "created", "livemode", "organization", "grant", "origin", "type", "data" ] }, "WebhookEndpointDisabledNotice": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^we_[0-9a-f]{32}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "status": { "type": "string", "const": "disabled_by_system" }, "reason": { "description": "`gone`: the receiver answered 410; `circuit_breaker`: 72 hours of failures.", "type": "string", "enum": [ "gone", "circuit_breaker" ] } }, "required": [ "id", "object", "status", "reason" ] }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Pass as `cursor` to fetch the next page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "WebhookReplay": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_replay" }, "queued": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "object", "queued" ] }, "WebhookTest": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_test" }, "event_id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "delivery_id": { "description": "The queued delivery (a ping is never answered without one).", "type": "string", "pattern": "^whd_[0-9a-f]{32}$" } }, "required": [ "object", "event_id", "delivery_id" ] } } }, "x-light-ai-scopes": [ "leads:read", "leads:write", "clients:read", "clients:write", "projects:read", "projects:write", "quotes:read", "quotes:write", "quotes:share_link", "quotes:asset_links", "webhooks:manage", "events:read", "mockups:read", "mockups:write", "forms:read", "forms:write" ], "x-light-ai-error-codes": [ { "code": "api_access_not_enabled", "status": 403, "title": "API access not enabled" }, { "code": "api_disabled", "status": 403, "title": "API disabled for this organization" }, { "code": "api_key_expired", "status": 401, "title": "API key expired" }, { "code": "api_key_revoked", "status": 401, "title": "API key revoked" }, { "code": "api_key_suspended", "status": 401, "title": "API key suspended" }, { "code": "authentication_required", "status": 401, "title": "Authentication required" }, { "code": "bad_request", "status": 400, "title": "Bad request" }, { "code": "billing_review_required", "status": 409, "title": "Billing review in progress" }, { "code": "conflict", "status": 409, "title": "Conflict" }, { "code": "daily_cap_reached", "status": 429, "title": "Daily cap reached" }, { "code": "forbidden", "status": 403, "title": "Forbidden" }, { "code": "idempotency_in_progress", "status": 409, "title": "Idempotent request in progress" }, { "code": "idempotency_key_reused", "status": 422, "title": "Idempotency key reused" }, { "code": "idempotency_scope_mismatch", "status": 409, "title": "Idempotency scope mismatch" }, { "code": "insufficient_credits", "status": 402, "title": "Insufficient credits" }, { "code": "insufficient_scope", "status": 403, "title": "Insufficient scope" }, { "code": "internal_error", "status": 500, "title": "Internal error" }, { "code": "invalid_api_key", "status": 401, "title": "Invalid API key" }, { "code": "ip_not_allowed", "status": 403, "title": "IP address not allowed" }, { "code": "limit_reached", "status": 409, "title": "Limit reached" }, { "code": "method_not_allowed", "status": 405, "title": "Method not allowed" }, { "code": "not_found", "status": 404, "title": "Not found" }, { "code": "organization_off_season", "status": 403, "title": "Organization on Off-Season" }, { "code": "organization_paused", "status": 403, "title": "Organization paused" }, { "code": "partner_spend_cap_reached", "status": 402, "title": "Partner spend cap reached" }, { "code": "payload_too_large", "status": 413, "title": "Payload too large" }, { "code": "plan_upgrade_required", "status": 403, "title": "Plan upgrade required" }, { "code": "quote_already_decided", "status": 409, "title": "Quote already decided" }, { "code": "quote_not_current", "status": 409, "title": "Quote is not current" }, { "code": "rate_limited", "status": 429, "title": "Rate limited" }, { "code": "service_unavailable", "status": 503, "title": "Service unavailable" }, { "code": "stale_state", "status": 409, "title": "Stale state" }, { "code": "step_up_required", "status": 428, "title": "Recent sign-in required" }, { "code": "test_mode_mismatch", "status": 400, "title": "Test mode mismatch" }, { "code": "test_mode_unsupported", "status": 400, "title": "Not available in test mode" }, { "code": "unsupported_api_version", "status": 400, "title": "Unsupported API version" }, { "code": "unsupported_media_type", "status": 415, "title": "Unsupported media type" }, { "code": "validation_failed", "status": 422, "title": "Validation failed" } ] }