SealDeal API

Authentication

Every request is authenticated with an API key belonging to exactly one organization. Mint keys at /admin/integrations/api-keys, choosing the scopes the key should carry. The secret is shown once at creation and stored only as a hash, so it cannot be recovered later.

curl https://sealdeal.ai/api/v1/me \
  -H "Authorization: Bearer obk_live_<your-secret>"

A missing header returns 401, an unknown or expired key returns 401, and a valid key that lacks the scope a route requires returns 403 naming the missing scope.

Quickstart

A first integration in four calls: check the key, create a list, add a contact to it, then read back the drafts SealDeal writes for that contact. The key needs lists.write, contacts.write and drafts.read.

export SEALDEAL_KEY=obk_live_<your-secret>
API=https://sealdeal.ai/api/v1

# 1. Which org and scopes does this key have?
curl -s $API/me -H "Authorization: Bearer $SEALDEAL_KEY"

# 2. Create a list. The Idempotency-Key makes a retry safe.
curl -s -X POST $API/lists \
  -H "Authorization: Bearer $SEALDEAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b2e-first-list" \
  -d '{"name": "Q4 webinar attendees", "sourceType": "CONFERENCE"}'

# 3. Add a contact to it (201 created, 200 if it already existed)
curl -s -X POST $API/contacts \
  -H "Authorization: Bearer $SEALDEAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId": "<list id>", "email": "dana@example.com", "name": "Dana Lee",
       "company": {"name": "Example Co", "domain": "example.com"}}'

# 4. Drafts arrive once the list generates; approve one to queue it for sending
curl -s "$API/drafts?contactId=<contact id>" -H "Authorization: Bearer $SEALDEAL_KEY"

Approving (POST /drafts/:id/approve, scope drafts.write) never sends by itself: approved drafts go out on their schedule through your workspace's verified mailbox. To be told when things happen instead of polling, subscribe a webhook.

Scopes

Rate limits

• Requests per API key in each fixed 60 second window, by plan: Starter 60, Team 120, Growth 300, Scale 600, Enterprise 1,200. It applies to every authenticated endpoint.
• All the keys in an organization together get twice that per window (Growth: 300 per key, 600 across every key). Past it, every key in the organization gets 429 until the window resets.
• Every response to an accepted key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds) for whichever limit is closer to running out, and X-RateLimit-Scope saying which one that is: key or organization.
• On exhaustion: 429 Too Many Requests with Retry-After (seconds until the window resets) and X-RateLimit-Remaining: 0.
• A batch request counts one unit per 10 rows (at least one), so a full 200 row batch costs 20 units, not 200.
• Mint one key per integration rather than sharing one across workflows: each key gets its own plan limit, up to the combined ceiling for the organization.

Idempotency

POST /lists, POST /deals and POST /deals/:id/activities accept an Idempotency-Key header (up to 255 characters), and so does every batch endpoint. Retrying with the same key returns what the first call created (for a batch, the same per row results) instead of creating it again, so a retry after a timeout is always safe. Reusing a key with a different body is a 422. POST /contacts, POST /sequences and POST /webhooks need no header: they are idempotent on the email, the contact and template pair, and the URL respectively.

Pagination

List endpoints return cursor paginated results:

{
  "data": [ ... ],
  "nextCursor": "eyJpZCI6Ii4uLiIsInQiOiIyMDI2LTA1LTIzVDEwOjAwOjAwLjAwMFoifQ"
}

Pass ?cursor=<value> on the next call to fetch the following page. A null nextCursor means the last page. Default page size is 50 and the maximum is 200, set with ?limit=. Contacts, companies and deals also take ?sort=createdAt|updatedAt|name and ?order=asc|desc, and ?include=total adds a total that respects every filter.

Syncing with another system

• Every list endpoint takes ?updatedSince= (ISO 8601), so a sync fetches only what changed since its last run; GET /events takes ?createdAfter=.
• PUT /contacts/by-external-id/:id and PUT /companies/by-external-id/:id create or update a record keyed by your own id, and ?externalId= finds it again.
• Batch endpoints for contacts and companies (200 rows), draft approve and reject (100) and suppression (500) answer with a result for every row, so one bad row never fails the rest.
• GET /members and GET /teams resolve the owner ids every record carries to a person and a team.

Long running work

Research can run in the background: POST /companies/:id/research?mode=async answers 202 with a job to poll at GET /research-jobs/:id, and a company.research_completed or contact.research_completed event fires when it lands. The research queue runs every minute, about 8 jobs per run and 4 at once, and organizations take turns, so a long queue from one customer never holds up another; a queued job usually lands within a minute or two. A questionnaire uploaded through POST /questionnaires is answered the same way: start it, then poll GET /questionnaires/:id until its status reads review. Its upload URL is signed for the sizeBytes you declared: PUT exactly that many bytes, or storage refuses the upload with 403 and stores nothing.

Errors

Error responses use RFC 7807 application/problem+json. The type URL is a real page: every problem type is documented at /errors, including whether retrying the same request can ever succeed.

{
  "type": "https://sealdeal.ai/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "The API key is missing required scopes: deals.write."
}

Endpoints

Webhooks

Register an endpoint with POST /api/v1/webhooks (or from /admin/integrations/webhooks), naming the event types to subscribe to. Retrieve the catalogue of available types from GET /api/v1/webhooks/events.

Deliveries arrive as a stable JSON envelope:

{
  "apiVersion": "2026-07-21",
  "id": "evt_2a7f9c00example",
  "type": "deal.won",
  "createdAt": "2026-07-21T10:14:00.000Z",
  "organizationId": "org_example",
  "data": { "dealId": "d_1", "dealName": "Acme, Platform" }
}

Each delivery carries an X-Outbound-Signature header in the form t=<unix-seconds>,v1=<hex>. Verify it by computing HMAC-SHA256("<t>." + rawBody, signingSecret) and comparing in constant time. The signing secret is returned when the endpoint is registered (registering the same URL again returns the current secret) and never by a GET. Rotate it with POST /api/v1/webhooks/:id/rotate-secret.

import crypto from 'node:crypto'

// rawBody: the exact bytes received, NOT JSON.stringify(parsedBody)
function verifySealDeal(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
  const t = Number(parts.t)
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest()
  const given = Buffer.from(parts.v1 ?? '', 'hex')
  return given.length === expected.length && crypto.timingSafeEqual(given, expected)
}

Rejecting a timestamp more than a few minutes old stops a captured delivery being replayed at you later. Failed deliveries are retried with backoff; after repeated failures the endpoint is marked dead and deliveries stop until you set it back to active. Inspect attempts with GET /api/v1/webhooks/:id/deliveries and replay an individual attempt if needed. The exact retry schedule, timeouts and every event's payload are in the webhooks guide.