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.
Three steps: a key, a first request, a first webhook.
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.
The response holds the whsec_… signing secret, once. Verify every delivery with it — see Webhooks. Prefer a UI? Settings → Developers → Webhooks does the same.
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.
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);
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.
Situation
Result
Same key, same body, first call finished
The stored response, replayed.
Same key, different body
422 — keys are single-use per request.
Same key while the first call is still running
409 — retry shortly.
First call failed with 5xx
Nothing stored; the retry runs the write.
Webhook create / rotate-secret replay
The subscription, with secret: null — secrets are never stored for replay. Rotate to get a new one.
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.
Delivery id — the same on every retry. De-duplicate on it: delivery is at-least-once.
webhook-timestamp
Unix seconds of this attempt.
webhook-signature
v1,<base64 HMAC-SHA256>, space-separated if several.
user-agent
Searagraph-Webhooks/1
content-type
application/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 attempt
Next attempt in
1
1 min
2
5 min
3
30 min
4
2 h
5
6 h
6
12 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.
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
Trigger: Webhooks by Zapier → Catch Hook. Copy the hook URL.
In Searagraph, create a webhook subscription with that URL and the events you want. Click Send test event so Zapier learns the shape.
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
Trigger: Webhooks → Custom webhook. Copy the address into a Searagraph subscription, then send a test event to determine the data structure.
Actions: HTTP → Make a request with the bearer header and a JSON body.
n8n
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.
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).
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
Name
In
Type
Required
Notes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
Request body
Field
Type
Required
Notes
email
string | null
max length 320
phone
string | null
max length 40
first_name
string | null
max length 200
last_name
string | null
max length 200
address_line1
string | null
max length 200
address_line2
string | null
max length 200
city
string | null
max length 200
state_region
string | null
max length 200
postal_code
string | null
max length 40
country
string | null
max length 100
opt_in_status
"granted" | "unknown" | "unsubscribed"
Email consent. A contact that unsubscribed can't be opted back in through the API.
custom
object
Registry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.
tags
string[]
Tag names (created when missing) or tag ids. Requires the tags.write scope.
Response 200
Field
Type
Required
Notes
data
object
yes
data.id
string
yes
Resource id (uuid).
data.email
string | null
yes
data.phone
string | null
yes
data.phone_e164
string | null
yes
data.first_name
string | null
yes
data.last_name
string | null
yes
data.address_line1
string | null
yes
data.address_line2
string | null
yes
data.city
string | null
yes
data.state_region
string | null
yes
data.postal_code
string | null
yes
data.country
string | null
yes
data.source
string
yes
data.opt_in_status
"granted" | "unknown" | "unsubscribed"
yes
data.opted_at
string | null
yes
ISO 8601 timestamp.
data.custom
object
yes
Custom field values keyed by registry key.
data.tags
object[]
yes
data.tags[].id
string
yes
Resource id (uuid).
data.tags[].name
string
yes
data.created_at
string
yes
ISO 8601 timestamp.
data.updated_at
string
yes
ISO 8601 timestamp.
outcome
"created" | "updated"
yes
restored
boolean
yes
True when the match was in trash and was restored.
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
Request body
Field
Type
Required
Notes
email
string | null
max length 320
phone
string | null
max length 40
first_name
string | null
max length 200
last_name
string | null
max length 200
address_line1
string | null
max length 200
address_line2
string | null
max length 200
city
string | null
max length 200
state_region
string | null
max length 200
postal_code
string | null
max length 40
country
string | null
max length 100
opt_in_status
"granted" | "unknown" | "unsubscribed"
Email consent. A contact that unsubscribed can't be opted back in through the API.
custom
object
Registry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
limit
query
integer
Page size (default 50, max 200).
cursor
query
string
Opaque cursor from a previous page's next_cursor.
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Response 200
Field
Type
Required
Notes
data
object[]
yes
data[].id
string
yes
Resource id (uuid).
data[].email
string | null
yes
data[].phone
string | null
yes
data[].phone_e164
string | null
yes
data[].first_name
string | null
yes
data[].last_name
string | null
yes
data[].address_line1
string | null
yes
data[].address_line2
string | null
yes
data[].city
string | null
yes
data[].state_region
string | null
yes
data[].postal_code
string | null
yes
data[].country
string | null
yes
data[].source
string
yes
data[].opt_in_status
"granted" | "unknown" | "unsubscribed"
yes
data[].opted_at
string | null
yes
ISO 8601 timestamp.
data[].custom
object
yes
Custom field values keyed by registry key.
data[].tags
object[]
yes
data[].tags[].id
string
yes
Resource id (uuid).
data[].tags[].name
string
yes
data[].created_at
string
yes
ISO 8601 timestamp.
data[].updated_at
string
yes
ISO 8601 timestamp.
next_cursor
string | null
yes
Pass as `cursor` to fetch the next page; null on the last page.
truncated
boolean
yes
True when this page stopped at the scan bound before filling; keep following next_cursor.
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
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.
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
Name
In
Type
Required
Notes
status
query
"active" | "disabled"
Only this status.
limit
query
integer
Page size (default 50, max 200).
cursor
query
string
Opaque cursor from a previous page's next_cursor.
Searagraph-Business-Id
header
string (uuid)
Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Response 200
Field
Type
Required
Notes
data
object[]
yes
data[].id
string
yes
Resource id (uuid).
data[].name
string
yes
data[].url
string
yes
The https endpoint deliveries are POSTed to.
data[].event_types
string[]
yes
data[].scope
"business" | "agency"
yes
`agency` = every business in the agency.
data[].business_id
string | null
yes
The business; null for agency-scope subscriptions.
data[].status
"active" | "disabled"
yes
data[].disabled_reason
string | null
yes
data[].consecutive_failures
integer
yes
Deliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data[].created_at
string
yes
ISO 8601 timestamp.
next_cursor
string | null
yes
Pass as `cursor` to fetch the next page; null on the last page.
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
Name
In
Type
Required
Notes
Searagraph-Business-Id
header
string (uuid)
Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
Request body
Field
Type
Required
Notes
name
string
yes
min length 1, max length 80
url
string
yes
https only; must resolve to a public address. — min length 1, max length 2048
event_types
(string (enum))[]
yes
at least 1
scope
"business" | "agency"
Default `business` (needs a business). `agency` = all businesses; agency-wide keys only.
Response 201
Field
Type
Required
Notes
data
object
yes
data.id
string
yes
Resource id (uuid).
data.name
string
yes
data.url
string
yes
The https endpoint deliveries are POSTed to.
data.event_types
string[]
yes
data.scope
"business" | "agency"
yes
`agency` = every business in the agency.
data.business_id
string | null
yes
The business; null for agency-scope subscriptions.
data.status
"active" | "disabled"
yes
data.disabled_reason
string | null
yes
data.consecutive_failures
integer
yes
Deliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
data.created_at
string
yes
ISO 8601 timestamp.
data.secret
string | null
yes
The `whsec_…` signing secret — returned once. null on an Idempotency-Key replay (rotate to get a new one).
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
Searagraph-Business-Id
header
string (uuid)
Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
Request body
Field
Type
Required
Notes
name
string
min length 1, max length 80
url
string
min 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
Field
Type
Required
Notes
data
object
yes
data.id
string
yes
Resource id (uuid).
data.name
string
yes
data.url
string
yes
The https endpoint deliveries are POSTed to.
data.event_types
string[]
yes
data.scope
"business" | "agency"
yes
`agency` = every business in the agency.
data.business_id
string | null
yes
The business; null for agency-scope subscriptions.
data.status
"active" | "disabled"
yes
data.disabled_reason
string | null
yes
data.consecutive_failures
integer
yes
Deliveries that exhausted every retry in a row; the subscription is disabled at 20. — ≥ -9007199254740991, ≤ 9007199254740991
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
Name
In
Type
Required
Notes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).
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
Name
In
Type
Required
Notes
id
path
string (uuid)
yes
Searagraph-Business-Id
header
string (uuid)
Required for agency-wide keys: the business to act on. Business keys may omit it.
Idempotency-Key
header
string
Makes the write safe to retry for 24 hours (same key + same body → same response).