Contact Capture Integration

Overview

The Contact Capture API turns any form submission into a Contact — a first-class person identity that exists before (and independently of) a logged-in user account. Every submission is deduplicated, enriched, and emits events that flow into segments, automations, inbox, campaigns, analytics, and AI.

Endpoint	Purpose
`POST /contacts`	Upsert a contact from a submission (creates or updates)
`POST /contacts/identify`	Resolve and identify an existing contact (never creates)

Base URL: https://api.hacktionbase.com/v1 Both endpoints are asynchronous: the submission is validated at the edge, accepted with 202, and queued. Deduplication, identity resolution, and event emission happen downstream within seconds.

Authentication

Both endpoints require a public API key (hb_public_*), sent as a Bearer token:

Authorization: Bearer hb_public_xxxxx

Public keys are issued from Settings → API Keys in the dashboard (key type Public). They can be rotated and revoked there at any time.

Public keys are secret server-side credentials — never embed them in browser code. If your form is client-side, proxy the submission through your own backend (see Server-side proxy pattern below).

Upsert a contact

POST /contacts accepts a form submission and either creates a new contact or updates the matching one.

curl -X POST https://api.hacktionbase.com/v1/contacts \
  -H "Authorization: Bearer hb_public_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+33612345678",
    "source": "website",
    "formId": "quote-form",
    "formType": "quote",
    "event": "quote.requested",
    "traits": {
      "company": "Acme Inc",
      "projectType": "redesign",
      "budget": "10-25k",
      "message": "We need a quote for..."
    },
    "consent": {
      "marketing": true,
      "termsAccepted": true
    }
  }'

Request fields

Field	Type	Notes
`externalUserId`	string	Your business identifier for the person (strongest matching key)
`anonymousId`	string	SDK anonymous visitor id, if known
`email`	string	Normalized (trim + lowercase) — the default dedup key
`phone`	string	Only used for matching when confidently parseable as E.164
`firstName`, `lastName`	string	Profile fields — never overwrite an existing value
`source`	string	Where the submission came from (e.g. `website`, `landing-page`)
`formId`, `formType`	string	Form provenance, stored in `sources[]`
`event`	string	Optional business event to emit alongside system events (e.g. `quote.requested`, `newsletter.subscribed`, `demo.requested`)
`traits`	object	Arbitrary custom attributes, stored opaque and merged per key
`consent`	object	`{ marketing?: boolean, termsAccepted?: boolean }` — timestamped on capture

At least one identifier (externalUserId, email, phone, or anonymousId) is required. Limits: string fields are capped at 2048 characters; traits is capped at 100 keys; keys containing $ or . are silently dropped. Provenance is captured automatically on every submission: ip, userAgent, and receivedAt are stored in the contact’s sources[] array along with source, formId, and formType.

Response

202 Accepted — the submission is queued for processing:

{
  "ok": true,
  "requestId": "9d2c5a44-6f9a-4a3e-b1a0-1234567890ab"
}

Downstream, the submission either creates a new contact or updates the matching one. When it matches two or more existing contacts, a new contact is still created — flagged identityStatus: "conflict" with the candidate ids in conflictsWith — and a contact.identity_conflict event is emitted. Conflicts are never auto-merged; resolve them from the dashboard (or by assigning the contact to a user).

Identify a contact

POST /contacts/identify resolves an existing contact and marks it identified — it never creates one. Use it when identity information arrives after the initial capture (e.g. the visitor signs up).

curl -X POST https://api.hacktionbase.com/v1/contacts/identify \
  -H "Authorization: Bearer hb_public_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "anon_8f3b2c",
    "email": "jane@acme.com",
    "externalUserId": "user_123"
  }'

The response is the same 202 Accepted acknowledgment. Downstream:

Match found — the contact is enriched and marked identified (contact.identified emitted).
No match — the submission is dropped (identify never creates; a later re-submission will re-identify).
Ambiguous match — nothing is merged; a contact.identity_conflict event is emitted and the conflict surfaces in the dashboard.

Identity resolution

Matching walks the identifiers in priority order over all active contacts (leads, anonymous visitors, and users):

externalUserId
email (normalized)
phone (E.164 only)
anonymousId

Resolution	Behavior
No match	New contact created (`kind: lead` if a strong identifier is present, else `anonymous`)
Single match	Contact updated — traits merged per key, profile fields enriched without overwriting
Match is a user	The user record is enriched (“the user always wins”) and `contact.merged` is emitted
Match is anonymous + strong id arrives	Promoted to `kind: lead`, `contact.identified` emitted
Multiple matches	Conflict — surfaced, never silently merged

Events

Every processed submission generates at least one event — there is no submission without an event. Events are written to the tenant event store during processing, then fanned out to the event bus (automations, segments, inbox, analytics, messaging, AI). System events: contact.created, contact.updated, contact.form_submitted, contact.identified, contact.merged, contact.identity_conflict. Business events: pass any name in the event field (e.g. quote.requested, newsletter.subscribed, demo.requested). Business events are dynamic — consolidate and map them per tenant in Analytics → Discovery with the Map Events modal.

Server-side proxy pattern

Keep the key on your server and forward form submissions from your own endpoint:

// Node.js / Express
app.post('/api/contact-form', async (req, res) => {
  const { email, firstName, lastName, message } = req.body;

  const response = await fetch('https://api.hacktionbase.com/v1/contacts', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.HB_PUBLIC_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      firstName,
      lastName,
      source: 'website',
      formId: 'contact-form',
      formType: 'contact',
      event: 'support.requested',
      traits: { message },
      consent: { marketing: !!req.body.marketing, termsAccepted: true },
    }),
  });

  // 202 — the submission is queued; processing happens downstream.
  res.status(response.ok ? 200 : 502).json({ ok: response.ok });
});

Pairing with the SDK: if the visitor is tracked by the Hacktionbase SDK, include its anonymous id in the submission (anonymousId) so the form contact links to the browsing session. The SDK exposes it via the session — the same id the widget uses for Hacktionbase.identify().

Error reference

Only edge validation errors are returned synchronously:

Status	Body	Meaning
`400`	`{ "error": "invalid_body" }`	Invalid or empty JSON body
`401`	`{ "error": "invalid_api_key" }`	Missing, revoked, or malformed public key
`429`	—	Rate limited

Business outcomes are resolved downstream and never fail the request: a submission with no identifier, an identify with no match, an exhausted trial contact quota, or a frozen trial tenant is dropped (logged server-side). Ambiguous matches emit a contact.identity_conflict event and surface in the dashboard.

Operations note — kind backfill migration

Deployments that predate the Contact model must run the kind backfill on every tenant DB before shipping this feature (otherwise legacy users become invisible to kind-scoped reads):

cd api && npm run migrate:contact-kind

The migration is idempotent and safe to re-run.

Overview

Endpoints

Contacts

Overview

Authentication

Upsert a contact

Request fields

Response

Identify a contact

Identity resolution

Events

Server-side proxy pattern

Error reference

Operations note — kind backfill migration

​Overview

​Authentication

​Upsert a contact

​Request fields

​Response

​Identify a contact

​Identity resolution

​Events

​Server-side proxy pattern

​Error reference

​Operations note — kind backfill migration

Overview

Authentication

Upsert a contact

Request fields

Response

Identify a contact

Identity resolution

Events

Server-side proxy pattern

Error reference

Operations note — kind backfill migration