HararAI API — Quickstart

1. Authentication

Every authenticated request includes an Authorization header carrying a Bearer token that starts with hrai_.

curl https://api.hararai.com/orgs/<your-org-id>/contacts \
  -H "Authorization: Bearer $HARARAI_API_KEY"

2. Send a lead

The simplest way to push a new lead into HararAI is to create a contact in your org. Replace <your-org-id> with the org ID shown alongside your API key. HararAI will create a CRM contact, fire downstream automations, and surface it in your inbox.

curl -X POST https://api.hararai.com/orgs/<your-org-id>/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HARARAI_API_KEY" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+61400000000",
    "source": "webform",
    "tags": ["website-quote-form"]
  }'

await fetch(
  `https://api.hararai.com/orgs/${ORG_ID}/contacts`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.HARARAI_API_KEY}`,
    },
    body: JSON.stringify({
      firstName: "Jane",
      lastName: "Smith",
      email: "jane@example.com",
      phone: "+61400000000",
      source: "webform",
      tags: ["website-quote-form"],
    }),
  },
);

Required fields: firstName, lastName. Everything else is optional. Valid source values: email, phone, manual, sms, webform, referral, google_ads, facebook_ads, yelp, import.

Public quote form (no auth): if you only need a website-form intake without managing keys, post to /api/leads/quote-request and identify the destination by brandSlug.

curl -X POST https://api.hararai.com/api/leads/quote-request \
  -H "Content-Type: application/json" \
  -d '{
    "brandSlug": "your-brand-slug",
    "name": "Jane Smith",
    "phone": "+61400000000",
    "email": "jane@example.com",
    "fromSuburb": "Bondi",
    "toSuburb": "Manly",
    "moveDate": "2026-05-15",
    "bedrooms": "2",
    "source": "website-quote-form"
  }'

3. Response format

Successful writes return 201 Created with the new resource wrapped in { data }.

{
  "data": {
    "id": "ctc_01H...",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+61400000000",
    "source": "webform",
    "status": "active",
    "createdAt": "2026-05-07T10:21:33.000Z"
  }
}

Errors always return JSON in the shape { error, code, status }.

{
  "error": "Invalid or revoked API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

Common codes: UNAUTHORIZED (missing / invalid key), VALIDATION_ERROR (bad payload), NOT_FOUND, FORBIDDEN, SERVICE_UNAVAILABLE.

4. Rate limits and scopes

All org-scoped routes are limited to 200 requests per minute per organization. Requests over the limit return 429 Too Many Requests with code: "RATE_LIMITED". API keys currently authenticate at member role (least-privilege) — per-key scopes are on the roadmap.

5. Next steps

• Manage your keys — mint, name, roll, or revoke API keys
• Browse all endpoints — full reference coming soon
• Need help? Email support@hararai.com