Identity API

Resolve anonymous visitors to known leads. The stitch endpoint is public for use by the snippet and SDK; other endpoints require authentication.

Get Visitor Journey

GET/api/identity

Retrieve a visitor's event history and identity data

Parameter	Type	Description
`visitorId`required	`string`	Anonymous visitor ID (query parameter)

curl "https://your-instance.com/api/identity?visitorId=v_abc123" \ -H "x-api-key: apex_key_abc123"

Returns the visitor's event timeline, any linked lead IDs, and attribution data:

{
  "visitorId": "v_abc123",
  "leadId": "lead_456",
  "firstSeen": "2025-01-10T08:00:00Z",
  "lastSeen": "2025-01-15T14:30:00Z",
  "events": [
    { "type": "pageview", "url": "/pricing", "timestamp": "2025-01-10T08:00:00Z" },
    { "type": "form_submit", "url": "/signup", "timestamp": "2025-01-15T14:30:00Z" }
  ],
  "attribution": {
    "channel": "organic_search",
    "source": "google",
    "landingPage": "/blog/growth-tips"
  }
}

Link Visitor to Lead

POST/api/identity

Manually stitch a visitor to a known lead

Used to link an anonymous visitor to a CRM lead when the association is known server-side (e.g. after a HubSpot webhook identifies the contact).

Parameter	Type	Description
`visitorId`required	`string`	Anonymous visitor ID to link
`leadId`required	`string`	Known lead or contact ID from your CRM
`source`	`string`	How the link was established (e.g. hubspot_webhook, manual)

curl -X POST https://your-instance.com/api/identity \ -H "Content-Type: application/json" \ -H "x-api-key: apex_key_abc123" \ -d '{ "visitorId": "v_abc123", "leadId": "lead_456", "source": "hubspot_webhook" }'

Email Stitch (Public)

POST/api/identity/stitch

Stitch a visitor to a lead via email — called by the snippet or SDK

Info

This endpoint is public and requires no authentication. It is designed to be called from the browser when a visitor submits their email.

Parameter	Type	Description
`visitorId`required	`string`	Anonymous visitor ID from the snippet
`email`required	`string`	Email address provided by the visitor
`projectKey`required	`string`	Your Apex project key

curl -X POST https://your-instance.com/api/identity/stitch \ -H "Content-Type: application/json" \ -d '{ "visitorId": "v_abc123", "email": "jane@example.com", "projectKey": "pk_live_xyz" }'

The API matches the email against known leads and merges the visitor's event history into the lead's journey. If no matching lead exists, one is created automatically.