{"openapi":"3.1.0","info":{"title":"AI CRM Nepal Automation API","version":"2026-10-11","description":"Authentication & setup: Sign in to the CRM and open Automation with a profile that has automation permission. Generate a workspace Bearer token, copy it to your server's secret storage and enable API lead intake. Send Authorization: Bearer YOUR_WORKSPACE_TOKEN and Content-Type: application/json. All six integration endpoints use POST with a JSON body, including reads. Tokens are workspace-scoped; do not send a workspace_id to switch tenants. Revoking or regenerating invalidates the old token. Intake, lead-details and task-create require intake to be enabled. The three update endpoints validate an active token but currently do not require that toggle to be on; revoke the token to stop every integration.\n\nChoose one lead identifier: For lead-details, lead-note, lead-pipeline and lead-assignee, at least one of crm_id, supabase_id, accounting_id or phone is compulsory. The same references optionally link task-create to a lead. Send only one identifier per request. If multiple are supplied, every provided value is validated, then lookup priority is CRM ID > Supabase ID > Accounting ID > phone. An ID that is not found never falls back to the phone. IDs are generated by the CRM and cannot be changed through these APIs. Always use IDs returned by your own workspace.\n\nResponse objects: Lead details return id, crm_id, supabase_id, accounting_id, name, phone, email, business_name, pan_vat_number, lead_date, next_follow_up_at, expected_budget, earned_amount, source, status, pipeline_stage, pipeline_option_id, pipeline_label, interested_option_id, interested_in, city_option_id, city_district, assignee_ids, assignee_labels, assignee, creator, latest_note, created_at and updated_at. Other lead-write endpoints return the lead snapshot with pipeline_display_label, interested_label, city_label and notes names rather than the details endpoint's display aliases. Nullable fields may be null. Notes contain id, content, created_at and author (id, full_name, email, role); author may be null.\n\nRate limits & errors: Request JSON is limited to 64 KiB (65,536 UTF-8 bytes), including chunked uploads. Oversized bodies return 413. Each workspace has a separate 60-second window per endpoint: intake 60 requests, each other integration endpoint 120. Read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds) and X-RateLimit-Policy when present; some early validation errors omit them. 429 includes Retry-After in seconds. Errors are JSON with error and sometimes fields, message or retryAfterSeconds. 400: invalid payload/options/member; 401: missing, invalid, revoked token or disabled required intake; 402: intake lead-plan limit; 403: intake workspace suspended; 404: lead not found in this workspace; 409: duplicate intake phone; 429: rate limit; 500: server failure. Retry 429 after Retry-After and transient server failures with bounded backoff. After an ambiguous write/network timeout, reconcile before retrying: note/task writes are not idempotent and can duplicate.\n\nCalling agents & accounting sync: Before a call, use lead-details with include_notes:true and drain every note page using its two-part cursor. Use include_notes:false for a faster current-field read when history is unnecessary. After the call, add the outcome through lead-note and create a follow-up task. Keep CRM, Supabase and Accounting IDs in your integration's mapping table. accounting_id is our internal ACC identifier; mapping to an external accounting customer ID is your integration's responsibility. Do not claim an accounting provider is already connected. Only the six documented operations are supported with workspace Bearer tokens: there is no external lead-list, arbitrary-field edit, delete, task-list or project API yet.\n\nWebhooks: events & delivery: In Automation, configure separate publicly reachable HTTPS URLs and enable the events you need: lead.created, lead.pipeline_changed, lead.assignee_changed and lead.follow_up_due. Standard event payloads have event, triggered_at, profile_id, workspace_id and lead. Stage-change adds previous_pipeline_stage and pipeline_stage. Assignee-change adds previous_assignees and assignees, and is skipped for default-only assignment. Follow-up-due adds event_id and scheduled_for. Standard lead webhook snapshots omit status/status_option_id/status_display_label; due-event snapshots currently include the stored lead fields. Creation, stage and assignment events attempt delivery up to three times with a 5-second timeout and 800/1600ms delays for retryable failures. Due events use a worker with up to five attempts and scheduled backoff; delivery timing depends on that worker. A successful API write is not confirmation that its webhook was delivered. Return 2xx promptly, process work asynchronously, and deduplicate due events using event_id.\n\nVerify webhook signatures: Read X-AI-CRM-Timestamp, X-AI-CRM-Signature, X-AI-CRM-Event, X-AI-CRM-Workspace, X-AI-CRM-Delivery-Attempt and X-AI-CRM-Delivery-ID. The signature is sha256= followed by HMAC-SHA256 using the workspace's current automation token over timestamp + '.' + the exact raw JSON body. Do not parse/re-serialize the body before verification. Use a timing-safe comparison, reject missing/invalid signatures, verify expected workspace/event and reject stale timestamps (for example a five-minute tolerance). Standard events may have an empty delivery ID; do not treat it as a universal deduplication key. Update the verification secret when rotating the token.\n\nBrowser and internal routes: Call integration endpoints from your backend or automation tool; no browser CORS support is promised. Never embed the Bearer token in frontend code, public URLs or AI prompts. /api/automation/settings (GET/PATCH) and /api/automation/token (POST: revoke/regenerate) are authenticated CRM-session management routes with automation permission and same-origin protection for writes. /api/automation/follow-up-dispatch (POST) is an internal worker route with a separate server secret. The application's /api/leads, /api/tasks, /api/projects, /api/analytics, /api/admin and account/settings routes are session/admin APIs, not workspace-token integration endpoints. Use the CRM UI to manage these features; do not substitute a Bearer token for a CRM session.","contact":{"name":"AI Automation Nepal","url":"https://www.aicrmnepal.com/about-ai-crm-nepal"}},"servers":[{"url":"https://www.aicrmnepal.com"}],"externalDocs":{"description":"Human-readable integration guide","url":"https://www.aicrmnepal.com/api-docs"},"components":{"schemas":{"Lead":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"business_name":{"type":"string"},"lead_date":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"pipeline_stage":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"id":{"type":"string","format":"uuid"},"crm_id":{"type":["string","null"]},"supabase_id":{"type":"string","format":"uuid"},"accounting_id":{"type":["string","null"]},"email":{"type":["string","null"]},"pan_vat_number":{"type":["string","null"]},"next_follow_up_at":{"type":["string","null"]},"expected_budget":{"type":"number"},"earned_amount":{"type":"number"},"pipeline_option_id":{"type":["string","null"]},"interested_option_id":{"type":["string","null"]},"city_option_id":{"type":["string","null"]},"assignee_ids":{"type":["array","null"],"items":{"type":"string"}},"assignee_labels":{"type":["array","null"],"items":{"type":"string"}},"assignee":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"creator":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"workspace_id":{"type":"string","format":"uuid"},"notes":{"type":"string"},"pipeline_display_label":{"type":["string","null"]},"interested_label":{"type":["string","null"]},"city_label":{"type":["string","null"]},"assigned_to":{"type":["string","null"]},"created_by":{"type":"string","format":"uuid"}},"additionalProperties":true},"LeadDetails":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"business_name":{"type":"string"},"lead_date":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"pipeline_stage":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"id":{"type":"string","format":"uuid"},"crm_id":{"type":["string","null"]},"supabase_id":{"type":"string","format":"uuid"},"accounting_id":{"type":["string","null"]},"email":{"type":["string","null"]},"pan_vat_number":{"type":["string","null"]},"next_follow_up_at":{"type":["string","null"]},"expected_budget":{"type":"number"},"earned_amount":{"type":"number"},"pipeline_option_id":{"type":["string","null"]},"interested_option_id":{"type":["string","null"]},"city_option_id":{"type":["string","null"]},"assignee_ids":{"type":["array","null"],"items":{"type":"string"}},"assignee_labels":{"type":["array","null"],"items":{"type":"string"}},"assignee":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"creator":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"latest_note":{"type":["string","null"]},"pipeline_label":{"type":["string","null"]},"interested_in":{"type":["string","null"]},"city_district":{"type":["string","null"]}}},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"author":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspace_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"assigned_to":{"type":"string","format":"uuid"},"created_by":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","in_progress","done"]},"priority":{"type":"string","enum":["low","medium","high"]},"due_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"lead_id":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"assignee":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}},"creator":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"full_name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}}}},"additionalProperties":true}},"securitySchemes":{"WorkspaceBearer":{"type":"http","scheme":"bearer","description":"Generate in the authenticated CRM Automation page. Do not use a Supabase key or browser session token."}}},"paths":{"/api/automation/intake":{"post":{"operationId":"intake","summary":"Create a lead","description":"Create a new lead with generated CRM, Supabase and Accounting identifiers. Existing phone numbers return 409; this endpoint does not upsert or update existing leads.\n\nGet the workspace's configured stage, interest, city and member values from its CRM settings; there is no Bearer-token options-discovery endpoint.\nWithout an assignee email, the configured default assignment is used. Invalid option/member values return 400.\nLead-plan capacity returns 402; a suspended workspace returns 403. Intake note history is processed asynchronously; do not assume the initial note is immediately in the paginated activity history.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":60,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200,"description":"Lead name, 2–200 characters after trimming."},"phone":{"type":"string","minLength":5,"maxLength":32,"description":"Required mobile number, 5–32 input characters and at least 7 digits; normalized before duplicate checking."},"email":{"type":"string","maxLength":320,"description":"Valid email address; empty string is accepted and stored as null."},"business_name":{"type":"string","maxLength":240,"description":"Business name. Default: empty string."},"pan_vat_number":{"type":"string","maxLength":100,"description":"PAN/VAT number. Default: null."},"lead_date":{"type":"string","description":"Valid YYYY-MM-DD. Omitted or empty: today's Nepal date."},"earned_amount":{"type":"number","minimum":0,"maximum":1000000000000,"default":0,"description":"NPR amount, 0–1,000,000,000,000. Default: 0. Numeric strings are also coerced."},"expected_budget":{"type":"number","minimum":0,"maximum":999999999999.99,"default":0,"description":"NPR amount, 0–999,999,999,999.99. Default: 0. Numeric strings are also coerced."},"source":{"type":"string","maxLength":100,"description":"Lead source. Default: Automation API."},"assignee_email":{"type":"string","maxLength":320,"description":"Email of an active member in this workspace. Alias: assigneeEmail."},"assigneeEmail":{"type":"string","maxLength":320,"description":"Alias for assignee_email. Email of an active member in this workspace. Alias: assigneeEmail."},"pipeline_stage":{"type":"string","maxLength":160,"description":"Configured stage label or value; omit for the default stage."},"pipeline_option_id":{"type":"string","maxLength":240,"description":"Configured stage option ID. If both ID and stage are sent, the server searches for either match; send one for clarity."},"interested_in":{"type":"string","maxLength":240,"description":"Configured interest label."},"interested_option_id":{"type":"string","maxLength":240,"description":"Configured interest option ID; omit both interest fields for no selection."},"city_district":{"type":"string","maxLength":240,"description":"Configured city/district label. Alias: city."},"city":{"type":"string","maxLength":240,"description":"Alias for city_district. Configured city/district label. Alias: city."},"city_option_id":{"type":"string","maxLength":240,"description":"Configured city option ID; omit both city fields for no selection."},"next_follow_up_at":{"type":"string","description":"Valid date/time. Prefer ISO 8601 with +05:45 or Z. Omitted/empty: null. Dates without an offset are interpreted in Asia/Kathmandu."},"notes":{"type":"string","maxLength":10000,"description":"Initial note. Default: empty string."}},"required":["name","phone"]},"example":{"name":"Example Customer","phone":"+9779800000000","source":"Calling agent","notes":"Requested a product walkthrough."}}}},"responses":{"201":{"description":"{ lead: Lead, identifiers: { crm_id, supabase_id, accounting_id } }","content":{"application/json":{"schema":{"type":"object","required":["lead","identifiers"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"changeActivities":{"type":"array","items":{"type":"object","additionalProperties":true}},"unchanged":{"type":"boolean"},"identifiers":{"type":"object","properties":{"crm_id":{"type":["string","null"]},"supabase_id":{"type":"string","format":"uuid"},"accounting_id":{"type":["string","null"]}}}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/automation/lead-details":{"post":{"operationId":"leadDetails","summary":"Read a lead and its notes","description":"Look up one lead in the token's workspace using any one of the four reference types. Read current fields quickly or page through conversation history.\n\nHistory contains note activities only, not every audit or stage-change activity. Order: newest created_at first, then descending note UUID.\nTo read all notes, keep requesting with BOTH returned cursor fields until has_more is false. include_notes:true alone returns only the first page.\nSuccessful responses are private, no-store. The documentation's sample IDs/numbers are illustrative and are not live customer records.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":120,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"crm_id":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"crmId":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Alias for crm_id. Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"supabase_id":{"type":"string","format":"uuid","description":"Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"supabaseId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"lead_id":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"leadId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"accounting_id":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"accountingId":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Alias for accounting_id. Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"phone":{"type":"string","maxLength":32,"description":"Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"lead_number":{"type":"string","maxLength":32,"description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"leadNumber":{"type":"string","maxLength":32,"description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"include_whatsapp_enquiries":{"type":"boolean","default":false,"description":"Default false. Include private WordPress WhatsApp enquiry page/title/time with independent pagination; normal Bearer and lead authorization required."},"whatsapp_enquiries_cursor":{"type":"string","maxLength":4000,"description":"Opaque whatsapp_enquiries.next_cursor, independent of notes/form pagination."},"whatsapp_enquiries_limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Page size 1–50, default20."},"include_form_submissions":{"type":"boolean","default":false,"description":"Default false. Include private form inquiry answers as form_submissions with independent pagination; lead access and normal Bearer authentication required."},"form_submissions_limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Form submissions per page:1–50, default20. Independent from notes_limit."},"form_submissions_cursor":{"type":"string","maxLength":4000,"description":"Opaque form_submissions.next_cursor from the same actor/workspace/lead. Follow until form_submissions.has_more is false; do not use note cursors."},"include_notes":{"type":"boolean","default":true,"description":"Default: true. false skips note-history fetching; notes is empty and has_more is false, but lead.latest_note remains available."},"notes_limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"1–100, default 50. Numeric strings are coerced. This is a page size, not the total note count."},"notes_before":{"type":"string","format":"date-time","description":"Optional ISO timestamp with offset from the previous next_cursor.created_at. Example: 2026-10-11T04:00:00Z."},"notes_before_id":{"type":"string","format":"uuid","description":"Use next_cursor.id with notes_before for stable pagination when timestamps are equal. On its own it does not filter notes."}},"required":[],"allOf":[{"anyOf":[{"required":["crm_id"]},{"required":["crmId"]},{"required":["supabase_id"]},{"required":["supabaseId"]},{"required":["lead_id"]},{"required":["leadId"]},{"required":["accounting_id"]},{"required":["accountingId"]},{"required":["phone"]},{"required":["lead_number"]},{"required":["leadNumber"]}]}]},"example":{"phone":"+9779800000000","include_notes":true,"notes_limit":100}}}},"responses":{"200":{"description":"{ lead: Lead, notes: Note[], notes_pagination: { included, limit, has_more, next_cursor }, form_submissions?: { submissions, has_more, next_cursor } }","content":{"application/json":{"schema":{"type":"object","required":["lead","notes","notes_pagination"],"properties":{"lead":{"$ref":"#/components/schemas/LeadDetails"},"changeActivities":{"type":"array","items":{"type":"object","additionalProperties":true}},"unchanged":{"type":"boolean"},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"notes_pagination":{"type":"object","required":["included","limit","has_more","next_cursor"],"properties":{"included":{"type":"boolean"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["object","null"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"}}}}}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/automation/lead-note":{"post":{"operationId":"leadNote","summary":"Add a lead note","description":"Append a note activity to the lead's history and replace the lead's latest-note summary.\n\nA successful response waits for note-history creation. Repeating the same request appends another activity; there is no idempotency key or automatic duplicate suppression.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":120,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"crm_id":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"crmId":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Alias for crm_id. Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"supabase_id":{"type":"string","format":"uuid","description":"Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"supabaseId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"lead_id":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"leadId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"accounting_id":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"accountingId":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Alias for accounting_id. Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"phone":{"type":"string","description":"Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"lead_number":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"leadNumber":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"note":{"type":"string","minLength":1,"description":"Non-empty after trimming. Alias: notes. No explicit maximum is enforced by this route; keep notes concise."},"notes":{"type":"string","minLength":1,"description":"Alias for note. Non-empty after trimming. Alias: notes. No explicit maximum is enforced by this route; keep notes concise."}},"required":[],"allOf":[{"anyOf":[{"required":["crm_id"]},{"required":["crmId"]},{"required":["supabase_id"]},{"required":["supabaseId"]},{"required":["lead_id"]},{"required":["leadId"]},{"required":["accounting_id"]},{"required":["accountingId"]},{"required":["phone"]},{"required":["lead_number"]},{"required":["leadNumber"]}]},{"anyOf":[{"required":["note"]},{"required":["notes"]}]}]},"example":{"crm_id":"CRM-000000000001","note":"Customer requested a callback tomorrow."}}}},"responses":{"200":{"description":"{ lead: Lead }","content":{"application/json":{"schema":{"type":"object","required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"changeActivities":{"type":"array","items":{"type":"object","additionalProperties":true}},"unchanged":{"type":"boolean"}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/automation/lead-pipeline":{"post":{"operationId":"leadPipeline","summary":"Update the lead stage","description":"Set a configured stage and derive the lead status from that stage. This existing API works with lead stages; it does not require a separate pipeline-board feature.\n\nProvide at least one stage selector. A matching option ID takes priority; if absent/invalid the server tries the stage, then label when stage is omitted. Use one valid selector to avoid ambiguity.\nThe same selection returns unchanged:true. Other selections may trigger the configured stage-change webhook.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":120,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"crm_id":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"crmId":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Alias for crm_id. Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"supabase_id":{"type":"string","format":"uuid","description":"Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"supabaseId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"lead_id":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"leadId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"accounting_id":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"accountingId":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Alias for accounting_id. Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"phone":{"type":"string","description":"Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"lead_number":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"leadNumber":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"pipeline_option_id":{"type":"string","description":"One stage selector is required. Configured stage option ID. Alias: pipelineOptionId."},"pipelineOptionId":{"type":"string","description":"Alias for pipeline_option_id. One stage selector is required. Configured stage option ID. Alias: pipelineOptionId."},"pipeline_stage":{"type":"string","description":"Configured stage ID, label or value. Alias: pipelineStage."},"pipelineStage":{"type":"string","description":"Alias for pipeline_stage. Configured stage ID, label or value. Alias: pipelineStage."},"pipeline_label":{"type":"string","description":"Configured stage display label. Alias: pipelineLabel."},"pipelineLabel":{"type":"string","description":"Alias for pipeline_label. Configured stage display label. Alias: pipelineLabel."}},"required":[],"allOf":[{"anyOf":[{"required":["crm_id"]},{"required":["crmId"]},{"required":["supabase_id"]},{"required":["supabaseId"]},{"required":["lead_id"]},{"required":["leadId"]},{"required":["accounting_id"]},{"required":["accountingId"]},{"required":["phone"]},{"required":["lead_number"]},{"required":["leadNumber"]}]},{"anyOf":[{"required":["pipeline_option_id"]},{"required":["pipelineOptionId"]},{"required":["pipeline_stage"]},{"required":["pipelineStage"]},{"required":["pipeline_label"]},{"required":["pipelineLabel"]}]}]},"example":{"accounting_id":"ACC-000000000001","pipeline_stage":"contacted"}}}},"responses":{"200":{"description":"{ lead: Lead, changeActivities?: Activity[], unchanged?: true }","content":{"application/json":{"schema":{"type":"object","required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"changeActivities":{"type":"array","items":{"type":"object","additionalProperties":true}},"unchanged":{"type":"boolean"}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/automation/lead-assignee":{"post":{"operationId":"leadAssignee","summary":"Change the lead assignee","description":"Assign one active team member by email, or reset to the configured default assignment.\n\nAn unknown or inactive member returns 400. Same assignment returns unchanged:true. The endpoint selects one member; it is not a multi-assignee write API.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":120,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"crm_id":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"crmId":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Alias for crm_id. Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"supabase_id":{"type":"string","format":"uuid","description":"Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"supabaseId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"lead_id":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"leadId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"accounting_id":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"accountingId":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Alias for accounting_id. Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"phone":{"type":"string","description":"Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"lead_number":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"leadNumber":{"type":"string","description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits."},"assignee_email":{"type":"string","description":"Optional active member email. Alias: assigneeEmail. Omitted or empty resets the lead to its configured default assignment; it does not preserve the current assignee."},"assigneeEmail":{"type":"string","description":"Alias for assignee_email. Optional active member email. Alias: assigneeEmail. Omitted or empty resets the lead to its configured default assignment; it does not preserve the current assignee."}},"required":[],"allOf":[{"anyOf":[{"required":["crm_id"]},{"required":["crmId"]},{"required":["supabase_id"]},{"required":["supabaseId"]},{"required":["lead_id"]},{"required":["leadId"]},{"required":["accounting_id"]},{"required":["accountingId"]},{"required":["phone"]},{"required":["lead_number"]},{"required":["leadNumber"]}]}]},"example":{"supabase_id":"00000000-0000-4000-8000-000000000001","assignee_email":"member@example.com"}}}},"responses":{"200":{"description":"{ lead: Lead, changeActivities?: Activity[], unchanged?: true }","content":{"application/json":{"schema":{"type":"object","required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"changeActivities":{"type":"array","items":{"type":"object","additionalProperties":true}},"unchanged":{"type":"boolean"}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/automation/task-create":{"post":{"operationId":"taskCreate","summary":"Create a task","description":"Create a task, optionally linked to a lead by phone or any of its three identifiers.\n\nLead reference fields are all optional here. If one is supplied, it must resolve in the workspace or the request fails; omitted: unlinked task.\nTask CRM IDs must already be uppercase. Accounting IDs are normalized to uppercase. Supabase/lead ID aliases must be UUIDs.\nTask response includes the generated task ID, workspace_id, assigned_to, created_by, title, description, status, priority, due_at, lead_id and timestamps. Default new status: open. This external API does not update task status.","security":[{"WorkspaceBearer":[]}],"x-rate-limit":{"requests":120,"windowSeconds":60,"scope":"workspace"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Task title, 1–200 characters after trimming."},"description":{"type":"string","maxLength":4000,"description":"Task details. Default: empty string."},"assignee_email":{"type":"string","format":"email","description":"Optional valid active member email. Alias: assigneeEmail. Omitted: token owner's profile ID. Empty string is invalid."},"assigneeEmail":{"type":"string","format":"email","description":"Alias for assignee_email. Optional valid active member email. Alias: assigneeEmail. Omitted: token owner's profile ID. Empty string is invalid."},"priority":{"type":"string","enum":["low","medium","high"],"default":"medium","description":"low, medium or high. Default: medium."},"due_at":{"type":"string","description":"Optional valid date/timestamp. Alias: deadline. Omitted/empty: no deadline. Prefer an explicit offset; offset-free values use Asia/Kathmandu."},"deadline":{"type":"string","description":"Alias for due_at. Optional valid date/timestamp. Alias: deadline. Omitted/empty: no deadline. Prefer an explicit offset; offset-free values use Asia/Kathmandu."},"crm_id":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"crmId":{"type":"string","pattern":"^CRM-[0-9]{12}$","description":"Alias for crm_id. Stable CRM ID: CRM- followed by 12 digits. Alias: crmId."},"supabase_id":{"type":"string","format":"uuid","description":"Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"supabaseId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"lead_id":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"leadId":{"type":"string","format":"uuid","description":"Alias for supabase_id. Lead UUID returned by the CRM. Aliases: supabaseId, lead_id, leadId."},"accounting_id":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"accountingId":{"type":"string","pattern":"^ACC-[0-9]{12}$","description":"Alias for accounting_id. Stable internal Accounting ID: ACC- followed by 12 digits. Alias: accountingId. This is not an external accounting vendor's customer ID."},"phone":{"type":"string","maxLength":64,"description":"Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits. Task inputs allow up to 64 characters."},"lead_number":{"type":"string","maxLength":64,"description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits. Task inputs allow up to 64 characters."},"leadNumber":{"type":"string","maxLength":64,"description":"Alias for phone. Mobile number. Aliases: lead_number, leadNumber. Nepal 10-digit numbers starting with 9 normalize to +977; formatted numbers normalize to digits with a + prefix. At least 7 digits. Task inputs allow up to 64 characters."}},"required":["title"]},"example":{"title":"Call customer back","priority":"high","due_at":"2026-10-11T11:00:00+05:45","phone":"+9779800000000"}}}},"responses":{"201":{"description":"{ task: Task, lead_reference: { crm_id, supabase_id, accounting_id } | null }","content":{"application/json":{"schema":{"type":"object","required":["task","lead_reference"],"properties":{"task":{"$ref":"#/components/schemas/Task"},"lead_reference":{"type":["object","null"],"properties":{"crm_id":{"type":["string","null"]},"supabase_id":{"type":"string","format":"uuid"},"accounting_id":{"type":["string","null"]}}}}}}}},"400":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"See public API reference error guide.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}}}}