Connect your tools.
Keep customer context.

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.

Base URL: https://www.aicrmnepal.com
Authorization: Bearer YOUR_WORKSPACE_TOKEN
Content-Type: application/json

Four ways to find one lead

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.

Endpoint reference

All operations below use POST and the workspace Bearer token. Required fields are marked explicitly. A lead reference is conditionally required for the four read/update endpoints; it is optional when creating a task.

Give your calling agent every note

include_notes: true includes one page, up to 100 notes. Fetch subsequent pages with both cursor fields until has_more is false. This example fails on HTTP errors so the agent does not silently use incomplete history.

// Node.js backend. Keep the workspace token in a secret environment variable.
const reference = { phone: "+9779800000000" }; // Or one of the three IDs.
const allNotes = [];
let cursor = null;
do {
  const response = await fetch("https://www.aicrmnepal.com/api/automation/lead-details", {
    method: "POST",
    headers: { Authorization: "Bearer " + process.env.CRM_AUTOMATION_TOKEN,
      "Content-Type": "application/json" },
    body: JSON.stringify({ ...reference, include_notes: true, notes_limit: 100,
      ...(cursor ? { notes_before: cursor.created_at, notes_before_id: cursor.id } : {}) })
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error || "CRM lookup failed");
  allNotes.push(...result.notes);
  cursor = result.notes_pagination.has_more ? result.notes_pagination.next_cursor : null;
} while (cursor);
// allNotes is newest-first. Reverse a copy for chronological agent context.
const chronologicalNotes = [...allNotes].reverse();

Illustrative lookup response

This abbreviated example shows the identifiers and note cursor; the actual lead object contains the fields described below.

{
  "lead": {
    "id": "00000000-0000-4000-8000-000000000001",
    "crm_id": "CRM-000000000001",
    "supabase_id": "00000000-0000-4000-8000-000000000001",
    "accounting_id": "ACC-000000000001",
    "name": "Example Customer",
    "phone": "+9779800000000",
    "email": null,
    "pipeline_stage": "contacted",
    "latest_note": "Requested a callback."
  },
  "notes": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "content": "Requested a callback.",
      "created_at": "2026-10-11T04:00:00Z",
      "author": null
    }
  ],
  "notes_pagination": {
    "included": true,
    "limit": 100,
    "has_more": false,
    "next_cursor": null
  }
}

Response 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.

Rate 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.

Calling 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.

Webhooks: 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.

Verify 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.

import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody must be the exact request body string; read it BEFORE parsing JSON.
function verifyWebhook(rawBody, timestamp, signature, expectedToken) {
  if (!timestamp || !signature || !expectedToken) return false;
  const age = Math.abs(Date.now() - Date.parse(timestamp));
  if (!Number.isFinite(age) || age > 5 * 60 * 1000) return false;
  const expected = "sha256=" + createHmac("sha256", expectedToken)
    .update(timestamp + "." + rawBody).digest("hex");
  const actualBytes = Buffer.from(signature);
  const expectedBytes = Buffer.from(expected);
  return actualBytes.length === expectedBytes.length &&
    timingSafeEqual(actualBytes, expectedBytes);
}
// Also verify the expected workspace/event before processing the parsed body.

Browser 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.