Use the REST API when your own systems need direct access to HAL data.

Base URL

https://api.chatwithhal.com/api

Authentication

HAL exposes more than one HTTP surface, so the authentication method depends on which route family you are calling.

• /api/widget/* is designed for customer-facing widget flows and uses project identification plus visitor identity input
• /api/* account routes use bearer-token authentication for signed-in HAL users and first-party backends
• /api/v1/* public integration routes use X-API-Key

Authorization: Bearer YOUR_TOKEN
X-API-Key: YOUR_API_KEY

Choose the right route family

Server-side event tracking

Use POST /api/v1/events/track when your backend knows that a customer, user, or company did something important and you do not have a HAL browser visitor_id. Authenticate with the project API key in X-API-Key.

curl -X POST "https://api.chatwithhal.com/api/v1/events/track" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "invoice.paid",
    "event_key": "invoice_789_paid",
    "value": 123.45,
    "entity": "company",
    "user_id": "user_123",
    "email": "buyer@example.com",
    "company_id": "company_456",
    "company": {
      "name": "Acme Ltd",
      "domain": "acme.example"
    },
    "occurred_at": "2026-06-26T10:00:00.000Z"
  }'

• Send at least one identity anchor: user_id, email, or company_id
• company_id is your external company identifier unless it already matches a HAL company ID
• event_key is optional but recommended for backend jobs and webhooks; re-sending the same key returns the existing event with deduped: true and does not re-run lifecycle campaign triggers
• value is optional and must be a string, number, boolean, or null
• HAL creates or reuses the minimal visitor, contact, company, and contact-company links needed for the event
• Tracked events appear in contact timelines, company activity, and inbox context

Lifecycle email campaigns created through MCP can use these event names as triggers. See Lifecycle email campaigns for event trigger, no-event-after, frequency scope, and predicate examples.

Performance notes

Event tracking is built for meaningful product and business milestones, not raw clickstream ingestion. HAL persists the event and resolves identity before returning so your backend knows the signal was accepted. Outgoing webhooks are queued asynchronously and do not block the caller.

For high-volume product activity, aggregate noisy actions in your app and send milestones such as invoice.paid, trial.started, subscription.renewed, or usage.limit_reached rather than every page view or button click.

Important note for CRM and identity sync

If your goal is to attach a live browser session to a signed-in customer, use the widget-facing identify flow. If your backend needs to record an event without browser state, use POST /api/v1/events/track.

The widget route family also includes CRM write endpoints such as POST /api/widget/set-stage and POST /api/widget/set-deal, plus tracked events through POST /api/widget/track, which backs window.HalWidget.track(...) in the browser widget.

Route selection for CRM sync

• Use /api/widget/identify when a product session or signed-in user should be mapped to HAL contacts and companies
• Use /api/widget/set-properties for follow-up visitor/contact metadata writes after identify
• Use /api/widget/track for browser-side milestone events with a required name and optional scalar value
• Use /api/v1/events/track for server-side milestone events keyed by your own user_id, email, or company_id
• Use /api/widget/set-stage and /api/widget/set-deal when the widget-side session should push company stage or deal changes
• Use account-authenticated /api/contacts and /api/companies routes when an authenticated HAL workspace user or first-party backend manages CRM records directly
• Use /api/v1 when an external integration with an API key only needs conversation or contact access

Current CRM write surfaces

What to use the API for

Typical resources

• Projects, visitors, and conversations
• CRM companies, contacts, and stages
• Knowledge-base and help-center content
• Team configuration and related settings

When to use MCP instead

If you are connecting an external AI client and want tool-style access rather than raw REST integration, use the hosted HTTP MCP endpoint instead of building your own orchestration on top of the REST API.