Identify API

The Identify API links an anonymous visitor to a known person and lets you fetch the latest identity record for that visitor.

🌐 Endpoints

POST/api/identify

Link a Ghost visitor ID to a known identity.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
siteId	number	No	Site that owns the visitor. Defaults to 4 if omitted.
ghost_vid	string	Yes	Visitor ID to identify.
user_id	string	Conditional	External user ID. Provide this or email.
email	string	Conditional	Known email address. Provide this or user_id.
name	string	No	Person name to store with the identity.
company	string	No	Company name to store with the identity.
phone	string	No	Phone number to store with the identity.
traits	object	No	Additional identity traits.
source	string	No	Source label for the identification event. Defaults to api.
source_detail	string	No	Optional source detail string.

Request Body

JSON

{
  "siteId": 4,
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "email": "user@example.com",
  "name": "Jane",
  "company": "Acme",
  "traits": {
    "plan": "enterprise",
    "role": "buyer"
  }
}

Example Request

Bash

curl --request POST \
  --url https://analytics.ghostid.ai/api/identify \
  --cookie "session=YOUR_SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{
    "siteId": 4,
    "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
    "email": "user@example.com",
    "name": "Jane",
    "company": "Acme",
    "traits": {
      "plan": "enterprise",
      "role": "buyer"
    }
  }'

Response Example

JSON

{
  "success": true,
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "identified_as": "user@example.com",
  "message": "Visitor identified successfully"
}

GET/api/identify

Return the latest identity record for a visitor.

🔑 Authentication required: Yes, via session cookie.

Parameters

Name	Type	Required	Description
ghost_vid	string	Yes	Visitor ID to look up.
siteId	number	No	Site that owns the visitor. Defaults to 4 if omitted.

Example Request

Bash

curl --request GET \
  --url "https://analytics.ghostid.ai/api/identify?ghost_vid=gv_a1b2c3d4_e5f6g7h8&siteId=4" \
  --cookie "session=YOUR_SESSION_COOKIE"

Response Example

JSON

{
  "ghost_vid": "gv_a1b2c3d4_e5f6g7h8",
  "identified": true,
  "identity": {
    "user_id": null,
    "email": "user@example.com",
    "name": "Jane",
    "company": "Acme",
    "phone": null,
    "traits": {
      "plan": "enterprise",
      "role": "buyer"
    },
    "source": "api",
    "identified_at": "2026-03-10T17:22:00.000Z"
  }
}

Webhooks