Embed API

Add capture and warm intro tracking to checkout, POS, or your website. Works on all plans with a publishable key.

Base URL

https://api.hearaboutus.com/v1

All requests use JSON. Responses include a standardized error object on failure.

Authentication

Use a publishable key (pk_live_…) in checkout embeds and client-side forms. Safe to include in browser code.

Pass your key via header or Bearer token:

X-HAU-Publishable-Key: pk_live_...
# or
Authorization: Bearer pk_live_...

Create keys in your dashboard →

Quick start — capture at checkout

Ask "How did you hear about us?" and create a warm intro in one call.

POST /v1/capture
X-HAU-Publishable-Key: pk_live_...
Content-Type: application/json

{
  "source_free_text": "Word of mouth",
  "advocate_name": "Sarah",
  "advocate_relationship": "friend",
  "note": "She recommended you highly"
}

{
  "event_id": "cap_xxx",
  "intro_id": "intro_xxx",
  "share_url": "https://www.hearaboutus.com/r/intro_xxx",
  "share_text": "I wanted to put in a good word for Acme Co.\n\n...",
  "business_name": "Acme Co"
}

Create a warm intro

POST /v1/intros
X-HAU-Publishable-Key: pk_live_...

{
  "advocate_name": "Sarah",
  "advocate_email": "sarah@example.com",
  "friend_email": "friend@example.com",
  "channel": "email",
  "metadata": { "order_id": "ord_123" }
}

Track intro progress

POST /v1/intros/:introId/track
Content-Type: application/json

{ "method": "link" }   // share event
{ "method": "click" }  // recipient opened link

Submit a good word

POST /v1/good-words
X-HAU-Publishable-Key: pk_live_...

{
  "moment": "Best service I've had in years — truly cared about the outcome.",
  "author_name": "Jordan",
  "context_type": "service"
}

Errors

Code	HTTP	Meaning
invalid_request	400	Missing or invalid field
invalid_key	401	Bad or revoked API key
rate_limit_exceeded	429	Too many requests

Rate limits

Publishable key: 60 requests/minute
Good word submissions: 3 per IP per 24 hours

Server-side API

Read your trust ledger, sync intros to your CRM, and receive webhook notifications with a secret key. Available on Agency and Ecosystem plans.

Merchant API documentation →