POST /api/v1/visitors/identify
/ Attach a stable visitor ID to a session. Memory and history follow the user from there.
Request
| Field | Type | Required | Description |
|---|---|---|---|
| agentId | string | Yes | The agent's public ID |
| sessionId | string | Yes | The anonymous session ID used so far |
| visitorId | string | Yes | Stable hashed ID for the now-known user. 1 to 255 characters |
const res = await fetch("https://app.humaner.io/api/v1/visitors/identify", {
method: "POST",
headers: {
Authorization: "Bearer hm_live_xxxxxxxx",
"Content-Type": "application/json"
},
body: JSON.stringify({
agentId: "AGENT_ID",
sessionId: "sess_xxx",
visitorId: "usr_hashed_123"
})
});Response
200 OK
{ "ok": true, "applied": true, "visitorId": "usr_hashed_123" }applied is false, memory unaffected, when the plan does not include personalization. On a plan with cross-session memory, everything under sessionId merges into visitorId.
Errors
| Status | Meaning |
|---|---|
| 400 | agentId, sessionId, or visitorId missing or invalid |
| 401 | Missing or invalid API key, or no Origin header and no key |
| 403 | Origin not on the allowed-domains list |
| 404 | Agent not found |
| 500 | Memory merge failed. Safe to retry |