api v1.0.0

Searagraph API

Read and write contacts, tags, custom fields, forms, segments, automations and campaigns, and receive signed webhooks when they change. JSON over HTTPS, bearer API keys, cursor pagination.

base url
https://searagraph.com/api/v1

Machine-readable: /api/v1/openapi.json (OpenAPI 3.1). Import it into Postman or Insomnia, or generate a client. Times are ISO 8601 UTC; ids are uuids; null clears a field on PATCH.

Contents

guide

Quickstart

Three steps: a key, a first request, a first webhook.

  1. Create a key.

    Settings → Developers → API keys. Name it after the integration, grant only the scopes it needs, set an expiry. The key is shown once — store it in your secret manager.

  2. Make a request.

    curl
    curl "https://searagraph.com/api/v1/contacts?limit=10" \
      -H "Authorization: Bearer sg_live_…"

    A list returns {data, next_cursor}. Every response carries X-Request-Id — quote it when something looks wrong.

  3. Subscribe to events.

    curl
    curl -X POST "https://searagraph.com/api/v1/webhooks" \
      -H "Authorization: Bearer sg_live_…" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: create-crm-sync-1" \
      -d '{"name":"CRM sync","url":"https://example.com/searagraph","event_types":["contact.created","form.submitted"]}'

    The response holds the whsec_… signing secret, once. Verify every delivery with it — see Webhooks. Prefer a UI? Settings → Developers → Webhooks does the same.

guide

Authentication & scopes

Send the key as a bearer token: Authorization: Bearer sg_live_…. A missing, invalid, revoked or expired key is a 401. Keys are created and revoked in Settings → Developers → API keys; rotation issues a new key and revokes the old one.

Business keys and agency-wide keys

A business key acts on its own business; no extra header. An agency-wide key acts on any business in the agency and names it on every business endpoint with Searagraph-Business-Id. List the ids with GET /businesses.

curl — agency-wide key
curl "https://searagraph.com/api/v1/contacts?limit=10" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Searagraph-Business-Id: <business id>"

A business it can't act on — another agency's, archived, or nonexistent — is the same 403, so ids can't be probed.

Scopes

A key does only what its scopes allow. A missing scope is a 403 whose message names it, with details.required_scope for machines.

ScopeGrantsEndpoints
contacts.readRead contactsGET /contactsGET /contacts/lookupGET /contacts/{id}
contacts.writeCreate, update and trash contactsPOST /contactsPOST /contacts/upsertPATCH /contacts/{id}DELETE /contacts/{id}
tags.readRead tagsGET /tags
tags.writeCreate tags and tag or untag contactsPOST /contacts/{id}/tagsDELETE /contacts/{id}/tags/{tag_id}POST /tagsPATCH /tags/{id}
custom_fields.readRead custom field definitionsGET /custom-fields
custom_fields.writeCreate and edit custom field definitionsPOST /custom-fieldsPATCH /custom-fields/{id}
forms.readRead formsGET /forms
submissions.readRead form submissionsGET /forms/{id}/submissions
segments.readRead segments and their membersGET /segmentsGET /segments/{id}/contacts
automations.readRead automationsGET /automations
automations.enrollAdd contacts to automationsPOST /automations/{id}/enrollments
campaigns.readRead campaigns and their statsGET /campaigns
webhooks.manageManage webhook subscriptionsGET /webhooksPOST /webhooksGET /webhooks/{id}PATCH /webhooks/{id}DELETE /webhooks/{id}GET /webhooks/{id}/deliveriesPOST /webhooks/{id}/rotate-secret
contacts.ingestLegacy contact ingest endpointLegacy POST /api/public/ingest/contacts only
pipelines.readRead pipelines and stagesGET /pipelines
opportunities.readRead opportunitiesGET /opportunitiesGET /opportunities/{id}
opportunities.writeCreate, update, move and archive opportunitiesPOST /opportunitiesPATCH /opportunities/{id}POST /opportunities/{id}/archivePOST /opportunities/{id}/restore

guide

Errors

Every non-2xx response has one envelope. Switch on code — the set is closed and the HTTP status is a function of it.

403 response
{
  "error": {
    "code": "forbidden",
    "message": "This API key is missing the \"contacts.write\" scope.",
    "request_id": "req_4f1c2a9e8b7d4c3a9e1f2b3c4d5e6f7a",
    "details": { "required_scope": "contacts.write" }
  }
}
CodeStatusMeaning
unauthorized401Missing, invalid, revoked or expired API key.
forbidden403The key lacks the required scope (named in the message), or can't act on that business.
not_found404The resource doesn't exist in this business.
conflict409Duplicate, already enrolled, or an Idempotency-Key request still in progress.
validation_failed422The request is invalid; `details.fields` lists each problem.
rate_limited429Too many requests; wait `Retry-After` seconds.
internal500Unexpected server error (reported). Retry with the same Idempotency-Key.

Validation errors list every problem at once in details.fields as {field, message}. A malformed id in a path is a 404.

guide

Rate limits

100 requests per 10 seconds per key, and 300 per 10 seconds per client IP. Every response reports the window:

HeaderMeaning
X-RateLimit-LimitRequests allowed per window.
X-RateLimit-RemainingRequests left in this window.
X-RateLimit-ResetUnix time (seconds) the window resets.
Retry-AfterOn 429 only: seconds to wait.

Over the limit is a 429 rate_limited. Wait Retry-After seconds, then retry. Back off on 5xx too:

JavaScript
async function call(url, init, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429 && res.status < 500) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 2 ** i);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("Searagraph API unavailable");
}

guide

Pagination

Lists take limit (default 50, max 200) and cursor, and return {data, next_cursor}. Pass next_cursor back as cursor until it is null. Cursors are opaque; don't build or edit them.

Lists run oldest first by creation time, so new rows land on later pages and a walk never skips one. Webhook deliveries run newest first. Filtered lists (contacts by tag_id, segment members) can return a short or empty page with a non-null cursor — keep following it.

JavaScript
let cursor = null;
do {
  const url = new URL("https://searagraph.com/api/v1/contacts");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SEARAGRAPH_API_KEY}` } });
  const page = await res.json();
  for (const contact of page.data) handle(contact);
  cursor = page.next_cursor;
} while (cursor);

guide

Idempotency

Writes (POST, PATCH, DELETE) accept Idempotency-Key: any unique string up to 255 printable ASCII characters. For 24 hours, a retry with the same key and the same body returns the first response, marked Idempotent-Replayed: true, without running the write again.

SituationResult
Same key, same body, first call finishedThe stored response, replayed.
Same key, different body422 — keys are single-use per request.
Same key while the first call is still running409 — retry shortly.
First call failed with 5xxNothing stored; the retry runs the write.
Webhook create / rotate-secret replayThe subscription, with secret: null — secrets are never stored for replay. Rotate to get a new one.

guide

Webhooks

A subscription receives a signed POST for each event it selects, usually within a minute. Manage them in Settings → Developers → Webhooks or through the webhooks endpoints. A new subscription never receives events from before it existed.

Body

data.object is the resource as it is when the delivery is sent; data.changesis the event's own payload (ids and changed field names — never personal data). An erased or missing resource is {"id", "deleted": true}; a trashed contact carries trashed: true.

contact.created body
{
  "id": 48213,
  "type": "contact.created",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "source": "api"
    }
  }
}

Headers

HeaderValue
webhook-idDelivery id — the same on every retry. De-duplicate on it: delivery is at-least-once.
webhook-timestampUnix seconds of this attempt.
webhook-signaturev1,<base64 HMAC-SHA256>, space-separated if several.
user-agentSearagraph-Webhooks/1
content-typeapplication/json

Verifying signatures

The scheme is Standard Webhooks (svix-compatible — those libraries work too). Sign ${webhook-id}.${webhook-timestamp}.${raw body} with HMAC-SHA256, keyed by the base64-decoded part of the whsec_…secret; compare in constant time; reject timestamps more than five minutes off. Use the raw body — re-serialized JSON won't match.

Node.js
import crypto from "node:crypto";

// secret = "whsec_..." from Searagraph. Use the RAW request body string.
export function verifySearagraphWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  // Reject stale or future messages (replay protection): 5 minutes.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  return signatures.split(" ").some((part) => {
    const [version, sig] = part.split(",");
    if (version !== "v1" || !sig) return false;
    const given = Buffer.from(sig, "base64");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}
// De-duplicate on headers["webhook-id"]: delivery is at-least-once.
Node.js — Express receiver
import express from "express";
import { verifySearagraphWebhook } from "./verify.js";

const app = express();
// Keep the RAW body: re-serialized JSON breaks the signature.
app.post("/searagraph", express.text({ type: "application/json" }), (req, res) => {
  if (!verifySearagraphWebhook(process.env.SEARAGRAPH_WEBHOOK_SECRET, req.headers, req.body)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  // ...enqueue your work; answer fast (10 s timeout) with any 2xx.
  res.sendStatus(204);
});
Python
import base64, hashlib, hmac, time

# secret = "whsec_..." from Searagraph. Use the RAW request body (bytes).
def verify_searagraph_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not (msg_id and timestamp and signatures):
        return False

    # Reject stale or future messages (replay protection): 5 minutes.
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for part in signatures.split(" "):
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False
# De-duplicate on headers["webhook-id"]: delivery is at-least-once.
PHP
<?php
// $secret = "whsec_..." from Searagraph. Use the RAW request body.
function verify_searagraph_webhook(string $secret, array $headers, string $rawBody): bool {
    $id = $headers['webhook-id'] ?? null;
    $timestamp = $headers['webhook-timestamp'] ?? null;
    $signatures = $headers['webhook-signature'] ?? null;
    if (!$id || !$timestamp || !$signatures) return false;

    // Reject stale or future messages (replay protection): 5 minutes.
    if (abs(time() - (int) $timestamp) > 300) return false;

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$rawBody}", $key, true));

    foreach (explode(' ', $signatures) as $part) {
        [$version, $sig] = array_pad(explode(',', $part, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $sig)) return true;
    }
    return false;
}

// Usage (plain PHP): header names lower-cased, body read once.
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
$raw = file_get_contents('php://input');
if (!verify_searagraph_webhook(getenv('SEARAGRAPH_WEBHOOK_SECRET'), $headers, $raw)) {
    http_response_code(401);
    exit;
}
// De-duplicate on $headers['webhook-id']: delivery is at-least-once.
http_response_code(204);

Responses, retries, auto-disable

Answer with any 2xx within 10 seconds. Anything else — non-2xx, a redirect (never followed), a timeout, a connection error — is a failed attempt. Failures retry on this schedule (7 attempts over about 20.6 h), then the delivery is failed:

After attemptNext attempt in
11 min
25 min
330 min
42 h
56 h
612 h

After 20 deliveries in a row fail every retry, the subscription is disabled. Fix the endpoint, then re-enable it (PATCH /webhooks/{id} with {"status": "active"}, or the Settings page). Endpoints must be https and resolve to public addresses — checked at creation and at every delivery.

reference

Event catalog

Subscribe by type. Names follow GoHighLevel's where one exists, so receivers port over. Expand a type for its sample body.

contact.createdA contact was created.GHL ContactCreate
contact.created body
{
  "id": 48213,
  "type": "contact.created",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "source": "api"
    }
  }
}
contact.updatedContact fields changed (payload lists field names).GHL ContactUpdate
contact.updated body
{
  "id": 48214,
  "type": "contact.updated",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "changed": [
        "first_name",
        "phone"
      ],
      "custom_changed": [
        "plan"
      ]
    }
  }
}
contact.dnd_updatedEmail consent status changed.GHL ContactDndUpdate
contact.dnd_updated body
{
  "id": 48215,
  "type": "contact.dnd_updated",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "unsubscribed",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "opt_in_status": "unsubscribed",
      "previous": "granted"
    }
  }
}
contact.tag_addedA tag was added to a contact.GHL ContactTagUpdate
contact.tag_added body
{
  "id": 48216,
  "type": "contact.tag_added",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "tag_id": "7c1e2d4a-0b9f-4c3e-8a21-5f6d7e8f9a0b"
    }
  }
}
contact.tag_removedA tag was removed from a contact.GHL ContactTagUpdate
contact.tag_removed body
{
  "id": 48217,
  "type": "contact.tag_removed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "tag_id": "7c1e2d4a-0b9f-4c3e-8a21-5f6d7e8f9a0b"
    }
  }
}
contact.trashedA contact was moved to trash.GHL ContactDelete
contact.trashed body
{
  "id": 48218,
  "type": "contact.trashed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ],
      "trashed": true,
      "trashed_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {}
  }
}
contact.restoredA contact was restored from trash.
contact.restored body
{
  "id": 48219,
  "type": "contact.restored",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "contact",
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "email": "jane@example.com",
      "phone": "+15555550123",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": null,
      "address_line2": null,
      "city": "Austin",
      "state_region": "TX",
      "postal_code": "78701",
      "country": "US",
      "source": "api",
      "custom": {
        "plan": "pro"
      },
      "opt_in_status": "granted",
      "opted_at": "2026-11-01T09:00:00.000Z",
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z",
      "tags": [
        "lead",
        "newsletter"
      ]
    },
    "changes": {
      "via": "app"
    }
  }
}
contact.erasedA contact's personal data was permanently erased.
contact.erased body
{
  "id": 48220,
  "type": "contact.erased",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "deleted": true
    },
    "changes": {}
  }
}
form.submittedA form submission completed.GHL FormSubmission
form.submitted body
{
  "id": 48221,
  "type": "form.submitted",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "form_submission",
      "id": "8a1c3e5f-7b9d-4f1a-8c3e-5f7b9d1f3a5c",
      "form_id": "3f9a6c2e-1d4b-4e8f-9a7c-2b5d8e1f4a6c",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "complete",
      "page_reached": 2,
      "data": {
        "email": "jane@example.com",
        "first_name": "Jane",
        "message": "Hello"
      },
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "form_id": "3f9a6c2e-1d4b-4e8f-9a7c-2b5d8e1f4a6c",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"
    }
  }
}
form.partial_capturedA multi-page form captured a partial submission.
form.partial_captured body
{
  "id": 48222,
  "type": "form.partial_captured",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "form_submission",
      "id": "8a1c3e5f-7b9d-4f1a-8c3e-5f7b9d1f3a5c",
      "form_id": "3f9a6c2e-1d4b-4e8f-9a7c-2b5d8e1f4a6c",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "partial",
      "page_reached": 2,
      "data": {
        "email": "jane@example.com",
        "first_name": "Jane",
        "message": "Hello"
      },
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "form_id": "3f9a6c2e-1d4b-4e8f-9a7c-2b5d8e1f4a6c",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "page_reached": 2
    }
  }
}
email.deliveredAn email was delivered.
email.delivered body
{
  "id": 48223,
  "type": "email.delivered",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "delivered",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": null,
      "clicked_at": null,
      "open_count": 0,
      "click_count": 0,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null
    }
  }
}
email.openedAn email was opened for the first time.
email.opened body
{
  "id": 48224,
  "type": "email.opened",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "delivered",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": "2026-11-18T14:03:12.000Z",
      "clicked_at": null,
      "open_count": 1,
      "click_count": 0,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null
    }
  }
}
email.clickedA link in an email was clicked for the first time.
email.clicked body
{
  "id": 48225,
  "type": "email.clicked",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "delivered",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": "2026-11-18T14:03:12.000Z",
      "clicked_at": "2026-11-18T14:03:12.000Z",
      "open_count": 1,
      "click_count": 1,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null
    }
  }
}
email.bouncedAn email bounced (payload has bounce_type).
email.bounced body
{
  "id": 48226,
  "type": "email.bounced",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "bounced",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": null,
      "clicked_at": null,
      "open_count": 0,
      "click_count": 0,
      "bounce_type": "hard",
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "bounce_type": "hard"
    }
  }
}
email.complainedA recipient marked an email as spam.
email.complained body
{
  "id": 48227,
  "type": "email.complained",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "complained",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": null,
      "clicked_at": null,
      "open_count": 0,
      "click_count": 0,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null
    }
  }
}
email.failedAn email could not be sent.
email.failed body
{
  "id": 48228,
  "type": "email.failed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "failed",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": null,
      "clicked_at": null,
      "open_count": 0,
      "click_count": 0,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null
    }
  }
}
email.unsubscribedA recipient unsubscribed.
email.unsubscribed body
{
  "id": 48229,
  "type": "email.unsubscribed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "email_send",
      "id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "automation_ref": null,
      "to_email": "jane@example.com",
      "status": "delivered",
      "sent_at": "2026-11-18T14:00:00.000Z",
      "opened_at": null,
      "clicked_at": null,
      "open_count": 0,
      "click_count": 0,
      "bounce_type": null,
      "created_at": "2026-11-18T13:59:58.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "campaign_id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "email_send_id": "9b1d3f5a-7c9e-4b1d-8f5a-7c9e1b3d5f7a"
    }
  }
}
automation.enrolledA contact entered an automation.
automation.enrolled body
{
  "id": 48230,
  "type": "automation.enrolled",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "automation_enrollment",
      "id": "4d6f8a0c-2e4a-4c6e-8a0c-2e4a6c8e0a2c",
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "active",
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"
    }
  }
}
automation.completedA contact finished an automation.
automation.completed body
{
  "id": 48231,
  "type": "automation.completed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "automation_enrollment",
      "id": "4d6f8a0c-2e4a-4c6e-8a0c-2e4a6c8e0a2c",
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "completed",
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"
    }
  }
}
automation.exitedA contact left an automation early.
automation.exited body
{
  "id": 48232,
  "type": "automation.exited",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "automation_enrollment",
      "id": "4d6f8a0c-2e4a-4c6e-8a0c-2e4a6c8e0a2c",
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "exited",
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"
    }
  }
}
automation.erroredAn automation run failed for a contact.
automation.errored body
{
  "id": 48233,
  "type": "automation.errored",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "automation_enrollment",
      "id": "4d6f8a0c-2e4a-4c6e-8a0c-2e4a6c8e0a2c",
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a",
      "status": "errored",
      "created_at": "2026-11-18T14:03:12.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "automation_id": "2e4a6c8e-0b2d-4f6a-8c0e-2b4d6f8a0c2e",
      "contact_id": "0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"
    }
  }
}
campaign.approvedA campaign was approved to send.
campaign.approved body
{
  "id": 48234,
  "type": "campaign.approved",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "campaign",
      "id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "name": "November newsletter",
      "status": "scheduled",
      "from_name": "Acme Dental",
      "from_email": "hello@acme.example",
      "approved_at": "2026-11-18T14:03:12.000Z",
      "scheduled_at": "2026-11-20T15:00:00.000Z",
      "sent_at": null,
      "archived_at": null,
      "created_at": "2026-11-10T10:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "mode": "scheduled",
      "scheduled_at": "2026-11-20T15:00:00.000Z"
    }
  }
}
campaign.scheduledA campaign was scheduled.
campaign.scheduled body
{
  "id": 48235,
  "type": "campaign.scheduled",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "campaign",
      "id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "name": "November newsletter",
      "status": "scheduled",
      "from_name": "Acme Dental",
      "from_email": "hello@acme.example",
      "approved_at": "2026-11-18T14:03:12.000Z",
      "scheduled_at": "2026-11-20T15:00:00.000Z",
      "sent_at": null,
      "archived_at": null,
      "created_at": "2026-11-10T10:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "scheduled_at": "2026-11-20T15:00:00.000Z"
    }
  }
}
campaign.pausedA sending campaign was paused.
campaign.paused body
{
  "id": 48236,
  "type": "campaign.paused",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "campaign",
      "id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "name": "November newsletter",
      "status": "paused",
      "from_name": "Acme Dental",
      "from_email": "hello@acme.example",
      "approved_at": "2026-11-18T14:03:12.000Z",
      "scheduled_at": "2026-11-20T15:00:00.000Z",
      "sent_at": null,
      "archived_at": null,
      "created_at": "2026-11-10T10:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "parked_jobs": 120
    }
  }
}
campaign.resumedA paused campaign resumed.
campaign.resumed body
{
  "id": 48237,
  "type": "campaign.resumed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "campaign",
      "id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "name": "November newsletter",
      "status": "sending",
      "from_name": "Acme Dental",
      "from_email": "hello@acme.example",
      "approved_at": "2026-11-18T14:03:12.000Z",
      "scheduled_at": "2026-11-20T15:00:00.000Z",
      "sent_at": null,
      "archived_at": null,
      "created_at": "2026-11-10T10:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "released_jobs": 120
    }
  }
}
campaign.cancelledA campaign was cancelled.
campaign.cancelled body
{
  "id": 48238,
  "type": "campaign.cancelled",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": {
      "object": "campaign",
      "id": "5a7c9e1b-3d5f-4a7c-8e1b-3d5f7a9c1e3b",
      "name": "November newsletter",
      "status": "cancelled",
      "from_name": "Acme Dental",
      "from_email": "hello@acme.example",
      "approved_at": "2026-11-18T14:03:12.000Z",
      "scheduled_at": "2026-11-20T15:00:00.000Z",
      "sent_at": null,
      "archived_at": null,
      "created_at": "2026-11-10T10:00:00.000Z",
      "updated_at": "2026-11-18T14:03:12.000Z"
    },
    "changes": {
      "from_status": "sending",
      "voided_sends": 42
    }
  }
}
contract.sentA contract was sent for signature.
contract.sent body
{
  "id": 48239,
  "type": "contract.sent",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "version_id": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c3e",
      "version": 2,
      "signer_count": 2
    }
  }
}
contract.viewedA signer opened their signing link.
contract.viewed body
{
  "id": 48240,
  "type": "contract.viewed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "signer_id": "1f3b5d7f-9a1c-4e3b-8d7f-9a1c3e5b7d9f",
      "role": "client"
    }
  }
}
contract.signedA signer signed a contract.
contract.signed body
{
  "id": 48241,
  "type": "contract.signed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "signer_id": "1f3b5d7f-9a1c-4e3b-8d7f-9a1c3e5b7d9f",
      "role": "client",
      "version": 2
    }
  }
}
contract.completedEvery required signer signed; the contract is locked.
contract.completed body
{
  "id": 48242,
  "type": "contract.completed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "version": 2,
      "document_id": "6d8f0a2c-4e6a-4c8e-9a2c-4e6a8c0e2a4c",
      "sealed": true,
      "seal_status": "sealed"
    }
  }
}
contract.voidedA contract was voided.
contract.voided body
{
  "id": 48243,
  "type": "contract.voided",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "previous_status": "out_for_signature"
    }
  }
}
invoice.postedAn invoice was posted to the books.
invoice.posted body
{
  "id": 48244,
  "type": "invoice.posted",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contract_id": "8b0d2f4a-6c8e-4a0b-9d2f-4a6c8e0b2d4f",
      "amount_cents": 500000,
      "currency": "usd"
    }
  }
}
payment.receivedA client payment was recorded.
payment.received body
{
  "id": 48245,
  "type": "payment.received",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "source": "whop",
      "contract_id": "8b0d2f4a-6c8e-4a0b-9d2f-4a6c8e0b2d4f",
      "invoice_id": null,
      "gross_cents": 500000,
      "currency": "usd"
    }
  }
}
payment.refundedA client payment was fully or partly refunded.
payment.refunded body
{
  "id": 48246,
  "type": "payment.refunded",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "adjustment_id": "3c5e7a9c-1e3b-4d5f-8a9c-1e3b5d7f9a1c",
      "amount_cents": 100000,
      "currency": "usd"
    }
  }
}
opportunity.createdAn opportunity was created.GHL OpportunityCreate
opportunity.created body
{
  "id": 48247,
  "type": "opportunity.created",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contact_id": "5d7f9b1d-3f5a-4b7d-9f1b-3d5f7b9d1f3a",
      "pipeline_id": "2e4a6c8e-0a2c-4e6a-8c0e-2a4c6e8a0c2e",
      "stage_id": "9a1c3e5a-7c9e-4a1c-8e5a-7c9e1a3c5e7a",
      "status": "open",
      "source": "manual",
      "actor_user_id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d4f"
    }
  }
}
opportunity.stage_changedAn opportunity moved to another stage or pipeline.GHL OpportunityStageUpdate
opportunity.stage_changed body
{
  "id": 48248,
  "type": "opportunity.stage_changed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contact_id": "5d7f9b1d-3f5a-4b7d-9f1b-3d5f7b9d1f3a",
      "pipeline_id": "2e4a6c8e-0a2c-4e6a-8c0e-2a4c6e8a0c2e",
      "stage_id": "4c6e8a0c-2e4a-4c6e-9a0c-2e4a6c8e0a2c",
      "previous_pipeline_id": "2e4a6c8e-0a2c-4e6a-8c0e-2a4c6e8a0c2e",
      "previous_stage_id": "9a1c3e5a-7c9e-4a1c-8e5a-7c9e1a3c5e7a",
      "actor_user_id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d4f"
    }
  }
}
opportunity.status_changedAn opportunity was won, lost, abandoned or reopened.GHL OpportunityStatusUpdate
opportunity.status_changed body
{
  "id": 48249,
  "type": "opportunity.status_changed",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contact_id": "5d7f9b1d-3f5a-4b7d-9f1b-3d5f7b9d1f3a",
      "status": "won",
      "previous": "open",
      "pipeline_id": "2e4a6c8e-0a2c-4e6a-8c0e-2a4c6e8a0c2e",
      "stage_id": "4c6e8a0c-2e4a-4c6e-9a0c-2e4a6c8e0a2c",
      "actor_user_id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d4f"
    }
  }
}
opportunity.updatedOpportunity fields changed (payload lists field names).GHL OpportunityUpdate
opportunity.updated body
{
  "id": 48250,
  "type": "opportunity.updated",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contact_id": "5d7f9b1d-3f5a-4b7d-9f1b-3d5f7b9d1f3a",
      "changed": [
        "value_cents",
        "owner_user_id"
      ],
      "actor_user_id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d4f"
    }
  }
}
opportunity.archivedAn opportunity was archived.GHL OpportunityDelete
opportunity.archived body
{
  "id": 48251,
  "type": "opportunity.archived",
  "occurred_at": "2026-11-18T14:03:12.000Z",
  "business_id": "6c2e8a4f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "data": {
    "object": null,
    "changes": {
      "contact_id": "5d7f9b1d-3f5a-4b7d-9f1b-3d5f7b9d1f3a",
      "pipeline_id": "2e4a6c8e-0a2c-4e6a-8c0e-2a4c6e8a0c2e"
    }
  }
}

guide

No-code recipes

Zapier, Make and n8n need no custom app: webhooks in, API key out. Treat a catch-hook URL as a secret — it is the only thing protecting it, since these tools don't verify signatures by default.

Zapier

  1. Trigger: Webhooks by Zapier → Catch Hook. Copy the hook URL.
  2. In Searagraph, create a webhook subscription with that URL and the events you want. Click Send test event so Zapier learns the shape.
  3. Actions back into Searagraph: Webhooks by Zapier → Custom Request, URL https://searagraph.com/api/v1/contacts/upsert, method POST, header Authorization: Bearer sg_live_…, JSON body.

Make

  1. Trigger: Webhooks → Custom webhook. Copy the address into a Searagraph subscription, then send a test event to determine the data structure.
  2. Actions: HTTP → Make a request with the bearer header and a JSON body.

n8n

  1. Trigger: a Webhook node (POST). Use its production URL in the subscription. To verify signatures, add a Code node with the Node.js verifier and the raw body.
  2. Actions: an HTTP Request node with a Header Auth credential (Authorization / Bearer sg_live_…).

Moving from GoHighLevel

GHL webhook names map to these event types. Bodies differ: the resource is under data.object, ids are uuids, and every delivery is signed. The rate limit matches GHL's (100 per 10 s).

GoHighLevelSearagraph
ContactCreatecontact.created
ContactUpdatecontact.updated
ContactDndUpdatecontact.dnd_updated
ContactTagUpdatecontact.tag_added
ContactTagUpdatecontact.tag_removed
ContactDeletecontact.trashed
FormSubmissionform.submitted
OpportunityCreateopportunity.created
OpportunityStageUpdateopportunity.stage_changed
OpportunityStatusUpdateopportunity.status_changed
OpportunityUpdateopportunity.updated
OpportunityDeleteopportunity.archived

endpoints

Contacts

List contacts

GET/api/v1/contacts→ 200

Scope contacts.read · Paginated.

Live contacts (trash excluded) in creation order. With `tag_id`, a page can come back short — keep following next_cursor until it is null.

Parameters

NameInTypeRequiredNotes
emailquerystringExact email match.
phonequerystringPhone match (normalized to E.164 when possible).
tag_idquerystring (uuid)Only contacts carrying this tag.
updated_sincequerystring (date-time)Only contacts updated at or after this time.
qquerystringSearch name, email and phone.
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].emailstring | nullyes
data[].phonestring | nullyes
data[].phone_e164string | nullyes
data[].first_namestring | nullyes
data[].last_namestring | nullyes
data[].address_line1string | nullyes
data[].address_line2string | nullyes
data[].citystring | nullyes
data[].state_regionstring | nullyes
data[].postal_codestring | nullyes
data[].countrystring | nullyes
data[].sourcestringyes
data[].opt_in_status"granted" | "unknown" | "unsubscribed"yes
data[].opted_atstring | nullyesISO 8601 timestamp.
data[].customobjectyesCustom field values keyed by registry key.
data[].tagsobject[]yes
data[].tags[].idstringyesResource id (uuid).
data[].tags[].namestringyes
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Find a contact by email or phone

GET/api/v1/contacts/lookup→ 200

Scope contacts.read

Pass exactly one of `email` or `phone`. Phone matches the oldest live contact with that E.164 number.

Parameters

NameInTypeRequiredNotes
emailquerystring
phonequerystring
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.emailstring | nullyes
data.phonestring | nullyes
data.phone_e164string | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.address_line1string | nullyes
data.address_line2string | nullyes
data.citystring | nullyes
data.state_regionstring | nullyes
data.postal_codestring | nullyes
data.countrystring | nullyes
data.sourcestringyes
data.opt_in_status"granted" | "unknown" | "unsubscribed"yes
data.opted_atstring | nullyesISO 8601 timestamp.
data.customobjectyesCustom field values keyed by registry key.
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl "https://searagraph.com/api/v1/contacts/lookup" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Get a contact

GET/api/v1/contacts/{id}→ 200

Scope contacts.read

Includes tags and custom field values.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.emailstring | nullyes
data.phonestring | nullyes
data.phone_e164string | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.address_line1string | nullyes
data.address_line2string | nullyes
data.citystring | nullyes
data.state_regionstring | nullyes
data.postal_codestring | nullyes
data.countrystring | nullyes
data.sourcestringyes
data.opt_in_status"granted" | "unknown" | "unsubscribed"yes
data.opted_atstring | nullyesISO 8601 timestamp.
data.customobjectyesCustom field values keyed by registry key.
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl "https://searagraph.com/api/v1/contacts/<id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Create a contact

POST/api/v1/contacts→ 201

Scope contacts.write

Needs an email or a phone. A duplicate email is a 409 carrying `details.existing_id` — use upsert to update instead.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
emailstring | nullmax length 320
phonestring | nullmax length 40
first_namestring | nullmax length 200
last_namestring | nullmax length 200
address_line1string | nullmax length 200
address_line2string | nullmax length 200
citystring | nullmax length 200
state_regionstring | nullmax length 200
postal_codestring | nullmax length 40
countrystring | nullmax length 100
opt_in_status"granted" | "unknown" | "unsubscribed"Email consent. A contact that unsubscribed can't be opted back in through the API.
customobjectRegistry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.
tagsstring[]Tag names (created when missing) or tag ids. Requires the tags.write scope.

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.emailstring | nullyes
data.phonestring | nullyes
data.phone_e164string | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.address_line1string | nullyes
data.address_line2string | nullyes
data.citystring | nullyes
data.state_regionstring | nullyes
data.postal_codestring | nullyes
data.countrystring | nullyes
data.sourcestringyes
data.opt_in_status"granted" | "unknown" | "unsubscribed"yes
data.opted_atstring | nullyesISO 8601 timestamp.
data.customobjectyesCustom field values keyed by registry key.
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/contacts" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","phone":"+15555550123"}'

Errors

401 unauthorized403 forbidden409 conflict422 validation_failed429 rate_limited500 internal

Create or update a contact

POST/api/v1/contacts/upsert→ 200

Scope contacts.write

Matches on email, then on E.164 phone (a phone match is used only when it can't clash with the body's email). A match is OVERWRITTEN with the fields sent (`null` clears); a match in trash is restored first. 201 when created, 200 when updated.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
emailstring | nullmax length 320
phonestring | nullmax length 40
first_namestring | nullmax length 200
last_namestring | nullmax length 200
address_line1string | nullmax length 200
address_line2string | nullmax length 200
citystring | nullmax length 200
state_regionstring | nullmax length 200
postal_codestring | nullmax length 40
countrystring | nullmax length 100
opt_in_status"granted" | "unknown" | "unsubscribed"Email consent. A contact that unsubscribed can't be opted back in through the API.
customobjectRegistry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.
tagsstring[]Tag names (created when missing) or tag ids. Requires the tags.write scope.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.emailstring | nullyes
data.phonestring | nullyes
data.phone_e164string | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.address_line1string | nullyes
data.address_line2string | nullyes
data.citystring | nullyes
data.state_regionstring | nullyes
data.postal_codestring | nullyes
data.countrystring | nullyes
data.sourcestringyes
data.opt_in_status"granted" | "unknown" | "unsubscribed"yes
data.opted_atstring | nullyesISO 8601 timestamp.
data.customobjectyesCustom field values keyed by registry key.
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.
outcome"created" | "updated"yes
restoredbooleanyesTrue when the match was in trash and was restored.

Example

curl
curl -X POST "https://searagraph.com/api/v1/contacts/upsert" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","phone":"+15555550123"}'

Errors

401 unauthorized403 forbidden409 conflict422 validation_failed429 rate_limited500 internal

Update a contact

PATCH/api/v1/contacts/{id}→ 200

Scope contacts.write

OVERWRITE semantics: each field sent replaces the stored value, `null` clears it, absent fields are untouched. custom keys are validated against the custom-field registry by kind; unknown keys are rejected.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
emailstring | nullmax length 320
phonestring | nullmax length 40
first_namestring | nullmax length 200
last_namestring | nullmax length 200
address_line1string | nullmax length 200
address_line2string | nullmax length 200
citystring | nullmax length 200
state_regionstring | nullmax length 200
postal_codestring | nullmax length 40
countrystring | nullmax length 100
opt_in_status"granted" | "unknown" | "unsubscribed"Email consent. A contact that unsubscribed can't be opted back in through the API.
customobjectRegistry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.emailstring | nullyes
data.phonestring | nullyes
data.phone_e164string | nullyes
data.first_namestring | nullyes
data.last_namestring | nullyes
data.address_line1string | nullyes
data.address_line2string | nullyes
data.citystring | nullyes
data.state_regionstring | nullyes
data.postal_codestring | nullyes
data.countrystring | nullyes
data.sourcestringyes
data.opt_in_status"granted" | "unknown" | "unsubscribed"yes
data.opted_atstring | nullyesISO 8601 timestamp.
data.customobjectyesCustom field values keyed by registry key.
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X PATCH "https://searagraph.com/api/v1/contacts/<id>" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","phone":"+15555550123"}'

Errors

401 unauthorized403 forbidden404 not_found409 conflict422 validation_failed429 rate_limited500 internal

Move a contact to trash

DELETE/api/v1/contacts/{id}→ 200

Scope contacts.write

Soft delete: the contact leaves every list and automation, and can be restored from Trash in the app (or by an upsert that matches it). Nothing is permanently deleted.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.trashedtrueyes

Example

curl
curl -X DELETE "https://searagraph.com/api/v1/contacts/<id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Tag a contact

POST/api/v1/contacts/{id}/tags→ 200

Scope tags.write

Each entry is a tag name (created when missing) or a tag id. Returns every tag on the contact.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
tagsstring[]yesTag names (created when missing) or tag ids. — at least 1

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.contact_idstringyesResource id (uuid).
data.tagsobject[]yes
data.tags[].idstringyesResource id (uuid).
data.tags[].namestringyes

Example

curl
curl -X POST "https://searagraph.com/api/v1/contacts/<id>/tags" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"tags":["lead"]}'

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Untag a contact

DELETE/api/v1/contacts/{id}/tags/{tag_id}→ 200

Scope tags.write

Removes the tag from this contact only (the tag itself stays). `removed` is false when it wasn't attached.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
tag_idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.contact_idstringyesResource id (uuid).
data.tag_idstringyesResource id (uuid).
data.removedbooleanyes

Example

curl
curl -X DELETE "https://searagraph.com/api/v1/contacts/<id>/tags/<tag_id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

endpoints

Tags

List tags

GET/api/v1/tags→ 200

Scope tags.read · Paginated.

Parameters

NameInTypeRequiredNotes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/tags?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Create a tag

POST/api/v1/tags→ 201

Scope tags.write

A duplicate name is a 409 carrying `details.existing_id`.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
namestringyesmin length 1, max length 100

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/tags" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Zapier"}'

Errors

401 unauthorized403 forbidden409 conflict422 validation_failed429 rate_limited500 internal

Rename a tag

PATCH/api/v1/tags/{id}→ 200

Scope tags.write

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
namestringyesmin length 1, max length 100

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X PATCH "https://searagraph.com/api/v1/tags/<id>" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Zapier"}'

Errors

401 unauthorized403 forbidden404 not_found409 conflict422 validation_failed429 rate_limited500 internal

endpoints

Custom fields

List custom field definitions

GET/api/v1/custom-fields→ 200

Scope custom_fields.read · Paginated.

Parameters

NameInTypeRequiredNotes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].keystringyesImmutable machine key (snake_case) — the key in contact.custom.
data[].labelstringyes
data[].kindstring (enum)yesone of 7 values
data[].optionsstring[]yes
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/custom-fields?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Create a custom field

POST/api/v1/custom-fields→ 201

Scope custom_fields.write

The key is derived from the label (snake_case) and is immutable. select / multiselect need options. A duplicate key is a 409.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
labelstringyesThe key is derived from the label once, then immutable. — min length 1, max length 120
kindstring (enum)yesone of 7 values
optionsstring[]Required for select / multiselect.

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.keystringyesImmutable machine key (snake_case) — the key in contact.custom.
data.labelstringyes
data.kindstring (enum)yesone of 7 values
data.optionsstring[]yes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/custom-fields" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"label":"Plan","kind":"text"}'

Errors

401 unauthorized403 forbidden409 conflict422 validation_failed429 rate_limited500 internal

Update a custom field

PATCH/api/v1/custom-fields/{id}→ 200

Scope custom_fields.write

Label and options only — key and kind are immutable (stored contact data references them).

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
labelstringmin length 1, max length 120
optionsstring[]

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.keystringyesImmutable machine key (snake_case) — the key in contact.custom.
data.labelstringyes
data.kindstring (enum)yesone of 7 values
data.optionsstring[]yes
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X PATCH "https://searagraph.com/api/v1/custom-fields/<id>" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"label":"Plan","options":["string"]}'

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

endpoints

Forms

List forms

GET/api/v1/forms→ 200

Scope forms.read · Paginated.

Parameters

NameInTypeRequiredNotes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].statusstringyesactive | paused | archived
data[].submission_countintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].last_submission_atstring | nullyesISO 8601 timestamp.
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/forms?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

List a form's submissions

GET/api/v1/forms/{id}/submissions→ 200

Scope submissions.read · Paginated.

`status=partial` lists abandoned multi-page captures; default lists both.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
statusquery"complete" | "partial"
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].form_idstringyesResource id (uuid).
data[].contact_idstring | nullyesResource id (uuid).
data[].status"complete" | "partial"yes
data[].dataobjectyes
data[].page_reachedinteger | nullyes≥ -9007199254740991, ≤ 9007199254740991
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/forms/<id>/submissions?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

endpoints

Segments

List segments

GET/api/v1/segments→ 200

Scope segments.read · Paginated.

Parameters

NameInTypeRequiredNotes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].rulesobjectyesSegment rules (v1 or v2 shape).
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/segments?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

List a segment's members

GET/api/v1/segments/{id}/contacts→ 200

Scope segments.read · Paginated.

Evaluates the segment's rules over live contacts in creation order. A page examines at most 5,000 contacts; when it stops there `truncated` is true and the page may be short — keep following next_cursor until it is null.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].emailstring | nullyes
data[].phonestring | nullyes
data[].phone_e164string | nullyes
data[].first_namestring | nullyes
data[].last_namestring | nullyes
data[].address_line1string | nullyes
data[].address_line2string | nullyes
data[].citystring | nullyes
data[].state_regionstring | nullyes
data[].postal_codestring | nullyes
data[].countrystring | nullyes
data[].sourcestringyes
data[].opt_in_status"granted" | "unknown" | "unsubscribed"yes
data[].opted_atstring | nullyesISO 8601 timestamp.
data[].customobjectyesCustom field values keyed by registry key.
data[].tagsobject[]yes
data[].tags[].idstringyesResource id (uuid).
data[].tags[].namestringyes
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.
truncatedbooleanyesTrue when this page stopped at the scan bound before filling; keep following next_cursor.

Example

curl
curl "https://searagraph.com/api/v1/segments/<id>/contacts?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

endpoints

Automations

List automations

GET/api/v1/automations→ 200

Scope automations.read · Paginated.

Parameters

NameInTypeRequiredNotes
statusquery"draft" | "active" | "paused" | "archived"
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].status"draft" | "active" | "paused" | "archived"yes
data[].trigger_typestringyes
data[].reentry_policy"once" | "always"yes
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/automations?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Add a contact to an automation

POST/api/v1/automations/{id}/enrollments→ 201

Scope automations.enroll

Only active automations accept enrollments, and the automation's re-entry policy applies: `once` refuses a contact that was ever enrolled, `always` refuses one that is currently active. Both refusals are a 409 with `details.reason`.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
contact_idstring (uuid)yes

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.automation_idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.status"active" | "completed" | "exited" | "errored"yes
data.created_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/automations/<id>/enrollments" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a"}'

Errors

401 unauthorized403 forbidden404 not_found409 conflict422 validation_failed429 rate_limited500 internal

endpoints

Campaigns

List campaigns with stats

GET/api/v1/campaigns→ 200

Scope campaigns.read · Paginated.

Stats use the canonical definitions: rates are over delivered (delivery rate over sent), as percentages; null when the denominator is zero.

Parameters

NameInTypeRequiredNotes
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].statusstringyesdraft | in_review | approved | sending | paused | sent | failed | cancelled
data[].segment_idstringyesResource id (uuid).
data[].template_idstringyesResource id (uuid).
data[].scheduled_atstring | nullyesISO 8601 timestamp.
data[].approved_atstring | nullyesISO 8601 timestamp.
data[].sent_atstring | nullyesISO 8601 timestamp.
data[].archived_atstring | nullyesISO 8601 timestamp.
data[].statsobjectyes
data[].stats.sentintegeryesReached the email provider. — ≥ -9007199254740991, ≤ 9007199254740991
data[].stats.deliveredintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].stats.unique_opensintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].stats.unique_clicksintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].stats.unsubscribedintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].stats.delivery_ratenumber | nullyesPercentage 0–100; null when the denominator is zero.
data[].stats.open_ratenumber | nullyesPercentage 0–100; null when the denominator is zero.
data[].stats.click_ratenumber | nullyesPercentage 0–100; null when the denominator is zero.
data[].stats.click_to_open_ratenumber | nullyesPercentage 0–100; null when the denominator is zero.
data[].stats.unsubscribe_ratenumber | nullyesPercentage 0–100; null when the denominator is zero.
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/campaigns?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

endpoints

Businesses

List the businesses this key can act on

GET/api/v1/businesses→ 200

Any valid key. · Agency-level: no Searagraph-Business-Id needed.

Agency-level: needs no Searagraph-Business-Id. An agency-wide key sees every non-archived business in its agency (send one of these ids as Searagraph-Business-Id); a business key sees its own business.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].statusstringyes

Example

curl
curl "https://searagraph.com/api/v1/businesses" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

endpoints

Webhooks

List webhook subscriptions

GET/api/v1/webhooks→ 200

Scope webhooks.manage · Paginated. · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Agency-wide keys may omit Searagraph-Business-Id to act across the agency; with it the call is narrowed to that business (plus agency-wide subscriptions).

Parameters

NameInTypeRequiredNotes
statusquery"active" | "disabled"Only this status.
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].urlstringyesThe https endpoint deliveries are POSTed to.
data[].event_typesstring[]yes
data[].scope"business" | "agency"yes`agency` = every business in the agency.
data[].business_idstring | nullyesThe business; null for agency-scope subscriptions.
data[].status"active" | "disabled"yes
data[].disabled_reasonstring | nullyes
data[].consecutive_failuresintegeryesDeliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data[].created_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/webhooks?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Create a webhook subscription

POST/api/v1/webhooks→ 201

Scope webhooks.manage · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

The URL must be https and resolve to a public address (checked now and at every delivery).

The response carries the `whsec_…` signing secret — the only time it is returned. Store it, then verify every delivery with it.

A subscription never receives events from before it was created.

Agency-wide keys may omit Searagraph-Business-Id to act across the agency; with it the call is narrowed to that business (plus agency-wide subscriptions).

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
namestringyesmin length 1, max length 80
urlstringyeshttps only; must resolve to a public address. — min length 1, max length 2048
event_types(string (enum))[]yesat least 1
scope"business" | "agency"Default `business` (needs a business). `agency` = all businesses; agency-wide keys only.

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.urlstringyesThe https endpoint deliveries are POSTed to.
data.event_typesstring[]yes
data.scope"business" | "agency"yes`agency` = every business in the agency.
data.business_idstring | nullyesThe business; null for agency-scope subscriptions.
data.status"active" | "disabled"yes
data.disabled_reasonstring | nullyes
data.consecutive_failuresintegeryesDeliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data.created_atstringyesISO 8601 timestamp.
data.secretstring | nullyesThe `whsec_…` signing secret — returned once. null on an Idempotency-Key replay (rotate to get a new one).

Example

curl
curl -X POST "https://searagraph.com/api/v1/webhooks" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Zapier","url":"https://hooks.zapier.com/hooks/catch/123/abc/","event_types":["contact.created"]}'

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Get a webhook subscription

GET/api/v1/webhooks/{id}→ 200

Scope webhooks.manage · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Never returns the secret — rotate it to issue a new one.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.urlstringyesThe https endpoint deliveries are POSTed to.
data.event_typesstring[]yes
data.scope"business" | "agency"yes`agency` = every business in the agency.
data.business_idstring | nullyesThe business; null for agency-scope subscriptions.
data.status"active" | "disabled"yes
data.disabled_reasonstring | nullyes
data.consecutive_failuresintegeryesDeliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data.created_atstringyesISO 8601 timestamp.

Example

curl
curl "https://searagraph.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Update a webhook subscription

PATCH/api/v1/webhooks/{id}→ 200

Scope webhooks.manage · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Change name, url, event_types or status. Scope is fixed at creation. Setting `status: active` re-enables a disabled subscription and resets its failure streak.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
namestringmin length 1, max length 80
urlstringmin length 1, max length 2048
event_types(string (enum))[]at least 1
status"active" | "disabled"`active` re-enables and resets the failure streak.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.urlstringyesThe https endpoint deliveries are POSTed to.
data.event_typesstring[]yes
data.scope"business" | "agency"yes`agency` = every business in the agency.
data.business_idstring | nullyesThe business; null for agency-scope subscriptions.
data.status"active" | "disabled"yes
data.disabled_reasonstring | nullyes
data.consecutive_failuresintegeryesDeliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data.created_atstringyesISO 8601 timestamp.

Example

curl
curl -X PATCH "https://searagraph.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Zapier","url":"https://hooks.zapier.com/hooks/catch/123/abc/"}'

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Delete a webhook subscription

DELETE/api/v1/webhooks/{id}→ 200

Scope webhooks.manage · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Permanent: the subscription and its delivery log are removed; queued deliveries are dropped.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.deletedtrueyes

Example

curl
curl -X DELETE "https://searagraph.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

List a subscription's deliveries

GET/api/v1/webhooks/{id}/deliveries→ 200

Scope webhooks.manage · Paginated. · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Newest first. Each delivery is one event to this endpoint, with its retry state and last response.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
statusquery"pending" | "succeeded" | "retrying" | "failed"Only this status.
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesDelivery id — the `webhook-id` header receivers de-duplicate on.
data[].event_idintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].event_typestring | nullyes
data[].status"pending" | "succeeded" | "retrying" | "failed"yes
data[].attemptsintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].last_status_codeinteger | nullyes≥ -9007199254740991, ≤ 9007199254740991
data[].last_errorstring | nullyes
data[].response_snippetstring | nullyesFirst 1 KB of the last response body.
data[].next_attempt_atstring | nullyesISO 8601 timestamp.
data[].delivered_atstring | nullyesISO 8601 timestamp.
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/webhooks/<id>/deliveries?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Rotate a subscription's signing secret

POST/api/v1/webhooks/{id}/rotate-secret→ 200

Scope webhooks.manage · Agency-wide keys may send Searagraph-Business-Id to narrow the call to one business.

Issues a new `whsec_…` secret, effective immediately, and returns it once. The old secret stops verifying.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.namestringyes
data.urlstringyesThe https endpoint deliveries are POSTed to.
data.event_typesstring[]yes
data.scope"business" | "agency"yes`agency` = every business in the agency.
data.business_idstring | nullyesThe business; null for agency-scope subscriptions.
data.status"active" | "disabled"yes
data.disabled_reasonstring | nullyes
data.consecutive_failuresintegeryesDeliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data.created_atstringyesISO 8601 timestamp.
data.secretstring | nullyesThe `whsec_…` signing secret — returned once. null on an Idempotency-Key replay (rotate to get a new one).

Example

curl
curl -X POST "https://searagraph.com/api/v1/webhooks/<id>/rotate-secret" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

endpoints

Pipelines

List pipelines

GET/api/v1/pipelines→ 200

Scope pipelines.read

Active pipelines in display order, each with its active stages in board order.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].namestringyes
data[].positionintegeryes≥ -9007199254740991, ≤ 9007199254740991
data[].is_defaultbooleanyesNew opportunities without a pipeline land here.
data[].stagesobject[]yesActive stages, in board order.
data[].stages[].idstringyesResource id (uuid).
data[].stages[].namestringyes
data[].stages[].positionintegeryesOrder within the pipeline (0 = first column). — ≥ -9007199254740991, ≤ 9007199254740991
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.

Example

curl
curl "https://searagraph.com/api/v1/pipelines" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

endpoints

Opportunities

List opportunities

GET/api/v1/opportunities→ 200

Scope opportunities.read · Paginated.

Non-archived opportunities in creation order.

Parameters

NameInTypeRequiredNotes
pipeline_idquerystring (uuid)
stage_idquerystring (uuid)
statusquery"open" | "won" | "lost" | "abandoned"
contact_idquerystring (uuid)
owner_user_idquerystring (uuid)
updated_sincequerystring (date-time)Only opportunities updated at or after this time.
limitqueryintegerPage size (default 50, max 200).
cursorquerystringOpaque cursor from a previous page's next_cursor.
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobject[]yes
data[].idstringyesResource id (uuid).
data[].contact_idstringyesResource id (uuid).
data[].pipeline_idstring | nullyesResource id (uuid).
data[].stage_idstring | nullyesResource id (uuid).
data[].namestringyes
data[].value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data[].currencystringyesISO 4217, lower case.
data[].status"open" | "won" | "lost" | "abandoned"yes
data[].lost_reasonstring | nullyes
data[].owner_user_idstring | nullyesResource id (uuid).
data[].expected_close_datestring | nullyesYYYY-MM-DD.
data[].servicesstring[]yes
data[].source"manual" | "intake" | "form" | "automation" | "api"yes
data[].stage_entered_atstringyesISO 8601 timestamp.
data[].closed_atstring | nullyesISO 8601 timestamp.
data[].archived_atstring | nullyesISO 8601 timestamp.
data[].created_atstringyesISO 8601 timestamp.
data[].updated_atstringyesISO 8601 timestamp.
next_cursorstring | nullyesPass as `cursor` to fetch the next page; null on the last page.

Example

curl
curl "https://searagraph.com/api/v1/opportunities?limit=50" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Get an opportunity

GET/api/v1/opportunities/{id}→ 200

Scope opportunities.read

Archived opportunities are returned too (`archived_at` set).

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.pipeline_idstring | nullyesResource id (uuid).
data.stage_idstring | nullyesResource id (uuid).
data.namestringyes
data.value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data.currencystringyesISO 4217, lower case.
data.status"open" | "won" | "lost" | "abandoned"yes
data.lost_reasonstring | nullyes
data.owner_user_idstring | nullyesResource id (uuid).
data.expected_close_datestring | nullyesYYYY-MM-DD.
data.servicesstring[]yes
data.source"manual" | "intake" | "form" | "automation" | "api"yes
data.stage_entered_atstringyesISO 8601 timestamp.
data.closed_atstring | nullyesISO 8601 timestamp.
data.archived_atstring | nullyesISO 8601 timestamp.
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl "https://searagraph.com/api/v1/opportunities/<id>" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Create an opportunity

POST/api/v1/opportunities→ 201

Scope opportunities.write

Opens a deal for a contact. Without `pipeline_id` it lands in the default pipeline; without `stage_id`, in the pipeline's first stage. Send an Idempotency-Key to make retries safe.

Parameters

NameInTypeRequiredNotes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
contact_idstring (uuid)yes
namestringyesmin length 1, max length 300
value_centsinteger | nullInteger cents; null clears. — ≥ 0, ≤ 9007199254740991
currencystringISO 4217 code, e.g. usd.
pipeline_idstring (uuid)Omit for the default pipeline.
stage_idstring (uuid)Omit for the pipeline's first stage.
owner_user_idstring (uuid) | nullA user with access to the business; null = unassigned.
expected_close_datestring (date) | null
servicesstring[]

Response 201

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.pipeline_idstring | nullyesResource id (uuid).
data.stage_idstring | nullyesResource id (uuid).
data.namestringyes
data.value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data.currencystringyesISO 4217, lower case.
data.status"open" | "won" | "lost" | "abandoned"yes
data.lost_reasonstring | nullyes
data.owner_user_idstring | nullyesResource id (uuid).
data.expected_close_datestring | nullyesYYYY-MM-DD.
data.servicesstring[]yes
data.source"manual" | "intake" | "form" | "automation" | "api"yes
data.stage_entered_atstringyesISO 8601 timestamp.
data.closed_atstring | nullyesISO 8601 timestamp.
data.archived_atstring | nullyesISO 8601 timestamp.
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/opportunities" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"0d8e2f4a-6b1c-4d3e-9f5a-7c2b4e6d8f1a","name":"Zapier"}'

Errors

401 unauthorized403 forbidden422 validation_failed429 rate_limited500 internal

Update, move or close an opportunity

PATCH/api/v1/opportunities/{id}→ 200

Scope opportunities.write

Fields sent replace the stored value (`null` clears); absent fields are untouched. `status` wins / loses / abandons / reopens the deal; `pipeline_id` / `stage_id` move it (appended to the end of the target column). Archived or archived-stage targets are refused (409 / 422). Archived opportunities must be restored first.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Request body

FieldTypeRequiredNotes
namestringmin length 1, max length 300
value_centsinteger | nullInteger cents; null clears. — ≥ 0, ≤ 9007199254740991
currencystringISO 4217 code, e.g. usd.
owner_user_idstring (uuid) | nullA user with access to the business; null = unassigned.
expected_close_datestring (date) | null
servicesstring[]
status"open" | "won" | "lost" | "abandoned"won / lost / abandoned close the deal; open reopens it.
lost_reasonstring | nullOnly with status lost (or on a lost deal). — max length 500
pipeline_idstring (uuid)Move to another pipeline (first stage unless stage_id is given).
stage_idstring (uuid)Move to this stage (appended to the end of the column).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.pipeline_idstring | nullyesResource id (uuid).
data.stage_idstring | nullyesResource id (uuid).
data.namestringyes
data.value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data.currencystringyesISO 4217, lower case.
data.status"open" | "won" | "lost" | "abandoned"yes
data.lost_reasonstring | nullyes
data.owner_user_idstring | nullyesResource id (uuid).
data.expected_close_datestring | nullyesYYYY-MM-DD.
data.servicesstring[]yes
data.source"manual" | "intake" | "form" | "automation" | "api"yes
data.stage_entered_atstringyesISO 8601 timestamp.
data.closed_atstring | nullyesISO 8601 timestamp.
data.archived_atstring | nullyesISO 8601 timestamp.
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X PATCH "https://searagraph.com/api/v1/opportunities/<id>" \
  -H "Authorization: Bearer sg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Zapier","value_cents":1}'

Errors

401 unauthorized403 forbidden404 not_found409 conflict422 validation_failed429 rate_limited500 internal

Archive an opportunity

POST/api/v1/opportunities/{id}/archive→ 200

Scope opportunities.write

Removes it from boards and lists; nothing is deleted. Restore with POST /opportunities/{id}/restore.

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.pipeline_idstring | nullyesResource id (uuid).
data.stage_idstring | nullyesResource id (uuid).
data.namestringyes
data.value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data.currencystringyesISO 4217, lower case.
data.status"open" | "won" | "lost" | "abandoned"yes
data.lost_reasonstring | nullyes
data.owner_user_idstring | nullyesResource id (uuid).
data.expected_close_datestring | nullyesYYYY-MM-DD.
data.servicesstring[]yes
data.source"manual" | "intake" | "form" | "automation" | "api"yes
data.stage_entered_atstringyesISO 8601 timestamp.
data.closed_atstring | nullyesISO 8601 timestamp.
data.archived_atstring | nullyesISO 8601 timestamp.
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/opportunities/<id>/archive" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal

Restore an archived opportunity

POST/api/v1/opportunities/{id}/restore→ 200

Scope opportunities.write

Back in place; when its stage or pipeline was archived meanwhile it moves to the first active stage (of its pipeline, else the default pipeline).

Parameters

NameInTypeRequiredNotes
idpathstring (uuid)yes
Searagraph-Business-Idheaderstring (uuid)Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-KeyheaderstringMakes the write safe to retry for 24 hours (same key + same body → same response).

Response 200

FieldTypeRequiredNotes
dataobjectyes
data.idstringyesResource id (uuid).
data.contact_idstringyesResource id (uuid).
data.pipeline_idstring | nullyesResource id (uuid).
data.stage_idstring | nullyesResource id (uuid).
data.namestringyes
data.value_centsinteger | nullyesInteger cents. — ≥ -9007199254740991, ≤ 9007199254740991
data.currencystringyesISO 4217, lower case.
data.status"open" | "won" | "lost" | "abandoned"yes
data.lost_reasonstring | nullyes
data.owner_user_idstring | nullyesResource id (uuid).
data.expected_close_datestring | nullyesYYYY-MM-DD.
data.servicesstring[]yes
data.source"manual" | "intake" | "form" | "automation" | "api"yes
data.stage_entered_atstringyesISO 8601 timestamp.
data.closed_atstring | nullyesISO 8601 timestamp.
data.archived_atstring | nullyesISO 8601 timestamp.
data.created_atstringyesISO 8601 timestamp.
data.updated_atstringyesISO 8601 timestamp.

Example

curl
curl -X POST "https://searagraph.com/api/v1/opportunities/<id>/restore" \
  -H "Authorization: Bearer sg_live_…"

Errors

401 unauthorized403 forbidden404 not_found422 validation_failed429 rate_limited500 internal