Public REST API (v1)

X-API-Key: YOUR_API_KEY

# or

Authorization: Bearer YOUR_API_KEY

BASE="https://YOUR-CLOSEUP-APP/api/v1"
LEAD_ID="3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11"
BODY='{"status":"closed","reason":"Signed the annual plan"}'

SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$CLOSEUP_SIGNING_SECRET" -hex | awk '{print $NF}')

curl -X PATCH "$BASE/leads/$LEAD_ID/status" \
  -H "X-API-Key: $CLOSEUP_API_KEY" \
  -H "X-CLL-Signature: sha256=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

import crypto from "node:crypto";

const BASE = "https://YOUR-CLOSEUP-APP/api/v1";

async function closeupRequest(method, path, payload) {
  const headers = { "X-API-Key": process.env.CLOSEUP_API_KEY };
  let body;

  if (payload !== undefined) {
    body = JSON.stringify(payload); // serialize once, sign and send this string
    const digest = crypto
      .createHmac("sha256", process.env.CLOSEUP_SIGNING_SECRET)
      .update(body, "utf8")
      .digest("hex");
    headers["Content-Type"] = "application/json";
    headers["X-CLL-Signature"] = "sha256=" + digest;
  }

  const res = await fetch(BASE + path, { method, headers, body });
  const json = await res.json();
  if (!json.ok) {
    throw new Error(json.error.code + ": " + json.error.message);
  }
  return json.data;
}

const data = await closeupRequest(
  "PATCH",
  "/leads/3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11/status",
  { status: "near_closure" }
);
console.log(data.previousStatus, "->", data.lead.status);

import hashlib
import hmac
import json
import os

import requests

BASE = "https://YOUR-CLOSEUP-APP/api/v1"
API_KEY = os.environ["CLOSEUP_API_KEY"]
SECRET = os.environ["CLOSEUP_SIGNING_SECRET"].encode()

payload = {"status": "near_closure"}
body = json.dumps(payload, separators=(",", ":"))  # serialize once
signature = hmac.new(SECRET, body.encode("utf-8"), hashlib.sha256).hexdigest()

resp = requests.patch(
    f"{BASE}/leads/3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11/status",
    data=body,  # send the exact signed string, not json=payload
    headers={
        "X-API-Key": API_KEY,
        "X-CLL-Signature": f"sha256={signature}",
        "Content-Type": "application/json",
    },
    timeout=15,
)
print(resp.status_code, resp.json())

{ "ok": true, "data": { "...": "..." } }

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Invalid request body.",
    "details": [
      { "field": "startAt", "message": "Invalid datetime" }
    ]
  }
}

GET /api/v1/leads/{leadId}/status

curl "https://YOUR-CLOSEUP-APP/api/v1/leads/3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11/status" \
  -H "X-API-Key: $CLOSEUP_API_KEY"

{
  "ok": true,
  "data": {
    "lead": {
      "id": "3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11",
      "name": "Dana Levi",
      "email": "dana@example.com",
      "phone": "0501234567",
      "status": "proposal_sent",
      "campaign": "Summer sale",
      "createdAt": "2026-01-04 09:12:00+00",
      "updatedAt": "2026-02-11 14:03:00+00"
    }
  }
}

PATCH /api/v1/leads/{leadId}/status
POST  /api/v1/leads/{leadId}/status   (alias, for clients that cannot send PATCH)

curl -X PATCH "https://YOUR-CLOSEUP-APP/api/v1/leads/3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11/status" \
  -H "X-API-Key: $CLOSEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"closed","reason":"Signed the annual plan","closedValueBasis":"proposal"}'

{
  "ok": true,
  "data": {
    "lead": {
      "id": "3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11",
      "name": "Dana Levi",
      "email": "dana@example.com",
      "phone": "0501234567",
      "status": "closed",
      "campaign": "Summer sale",
      "createdAt": "2026-01-04 09:12:00+00",
      "updatedAt": "2026-03-02 10:41:07+00"
    },
    "previousStatus": "proposal_sent"
  }
}

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Unknown status \"won\".",
    "details": {
      "allowedStatuses": [
        "new", "awaiting_proposal", "proposal_sent", "near_closure", "closed",
        "not_interested", "irrelevant", "follow_up_later", "paused"
      ]
    }
  }
}

POST /api/v1/appointments

curl -X POST "https://YOUR-CLOSEUP-APP/api/v1/appointments" \
  -H "X-API-Key: $CLOSEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11",
    "title": "Site survey",
    "startAt": "2026-03-04T11:00:00+02:00",
    "durationMinutes": 30,
    "timezone": "Asia/Jerusalem",
    "type": "in_person",
    "location": "Rothschild 12, Tel Aviv",
    "idempotencyKey": "booking-9c1f6e2a-55d4-4b0e-a1c7-2f8e3b6d9a40",
    "attendees": [
      { "email": "dana@example.com", "displayName": "Dana Levi" }
    ]
  }'

{
  "ok": true,
  "data": {
    "appointment": {
      "id": "b2e4d7a9-1c3f-4e8b-9a6d-0f5c2e7b1a34",
      "leadId": "3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11",
      "assignedUserId": "8a1d3c5e-7f9b-4d2a-b6c8-e0f2a4c6d8e1",
      "title": "Site survey",
      "startAt": "2026-03-04T09:00:00.000Z",
      "endAt": "2026-03-04T09:30:00.000Z",
      "timezone": "Asia/Jerusalem",
      "type": "in_person",
      "location": "Rothschild 12, Tel Aviv",
      "status": "scheduled",
      "notes": null,
      "videoJoinUrl": null,
      "sync": { "status": "not_applicable", "error": null, "lastSyncedAt": null },
      "rescheduleCount": 0,
      "cancelledAt": null,
      "completedAt": null,
      "createdAt": "2026-02-11T14:03:00.000Z",
      "updatedAt": "2026-02-11T14:03:00.000Z",
      "attendees": [
        {
          "kind": "organizer",
          "userId": "8a1d3c5e-7f9b-4d2a-b6c8-e0f2a4c6d8e1",
          "email": "rep@yourcompany.com",
          "displayName": "Yossi Cohen"
        },
        {
          "kind": "external",
          "userId": null,
          "email": "dana@example.com",
          "displayName": "Dana Levi"
        }
      ]
    }
  }
}

GET /api/v1/appointments?leadId={leadId}

curl "https://YOUR-CLOSEUP-APP/api/v1/appointments?leadId=3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11&status=scheduled&from=2026-03-01T00:00:00.000Z" \
  -H "X-API-Key: $CLOSEUP_API_KEY"

{
  "ok": true,
  "data": {
    "appointments": [
      {
        "id": "b2e4d7a9-1c3f-4e8b-9a6d-0f5c2e7b1a34",
        "leadId": "3f6c2a1e-8b7d-4c3a-9e21-5d4f0b7a6c11",
        "title": "Site survey",
        "startAt": "2026-03-04T09:00:00.000Z",
        "endAt": "2026-03-04T09:30:00.000Z",
        "status": "scheduled",
        "...": "same shape as the appointment object"
      }
    ]
  }
}

GET /api/v1/appointments/{appointmentId}

PATCH /api/v1/appointments/{appointmentId}
POST  /api/v1/appointments/{appointmentId}   (alias)

curl -X PATCH "https://YOUR-CLOSEUP-APP/api/v1/appointments/b2e4d7a9-1c3f-4e8b-9a6d-0f5c2e7b1a34" \
  -H "X-API-Key: $CLOSEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"startAt":"2026-03-05T14:00:00+02:00","durationMinutes":45}'

curl -X PATCH "https://YOUR-CLOSEUP-APP/api/v1/appointments/b2e4d7a9-1c3f-4e8b-9a6d-0f5c2e7b1a34" \
  -H "X-API-Key: $CLOSEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"no_show"}'

{
  "ok": false,
  "error": { "code": "conflict", "message": "Appointment is already cancelled." }
}