Join us now
← Back to API Reference overview

Visitors

Identify and manage visitors. Accepts system fields like $email, $phone and arbitrary key/value attributes.

Shortcut: ⌘K

#The Visitor object

Visitor represents a unique visitor profile

attributes

object

createdAt

string (date-time)

devices

array<object>

email

string

from "$email"

events

array<object>

firstName

string

id

string

lastName

string

links

array<object>

phone

string

updatedAt

string (date-time)

workspaceId

string
GET/v1/visitorsRequires auth

#List visitors

#Parameters

query parameters

limit

integer (int32)query

default 50, max 200

offset

integer (int32)query

default 0

email

stringquery

optional exact match filter

q

stringquery

optional fuzzy search across known fields

include

array<string>query

linkId

stringquery

optional filter by link ID (visitors who have interacted with this link)

responseFormat

stringquery

response format (JSON or CSV)

#Response

200

Everything worked as expected.

csv

object

json

object

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

GET/v1/visitors/{id}Requires auth

#Get a visitor

#Parameters

path parameters

id

stringRequiredpath

query parameters

include

array<string>query

#Response

200

Everything worked as expected.

attributes

object

createdAt

string (date-time)

devices

array<object>

email

string

from "$email"

events

array<object>

firstName

string

id

string

lastName

string

links

array<object>

phone

string

updatedAt

string (date-time)

workspaceId

string

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

POST/v1/visitor/identifyRequires auth

#Identify visitor

Accepts a payload with $-prefixed system fields (e.g., $email, $phone) and arbitrary attributes. The LBID (base64 encoded event ID) is used to resolve the correct workspace and associate to the underlying visitor/device. Note: To get the LBID, you must enable conversion tracking on the link.

#Parameters

This endpoint does not accept any parameters.

#Request body

lbid

string

setOnce

boolean

visitor

object

Input payload for identifying/updating a visitor - Reserved keys (system fields) have a "$" prefix, e.g. "$email", "$phone", "$first_name", "$last_name". - All other keys are treated as custom attributes and stored in `attributes`.

#Response

200

Everything worked as expected.

created

boolean

visitor

object

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

PATCH/v1/visitors/{id}Requires auth

#Update a visitor

#Parameters

path parameters

id

stringRequiredpath

#Request body

visitor

object

Input payload for identifying/updating a visitor - Reserved keys (system fields) have a "$" prefix, e.g. "$email", "$phone", "$first_name", "$last_name". - All other keys are treated as custom attributes and stored in `attributes`.

#Response

200

Everything worked as expected.

attributes

object

createdAt

string (date-time)

devices

array<object>

email

string

from "$email"

events

array<object>

firstName

string

id

string

lastName

string

links

array<object>

phone

string

updatedAt

string (date-time)

workspaceId

string

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

DELETE/v1/visitors/{id}Requires auth

#Delete a visitor

#Parameters

path parameters

id

stringRequiredpath

#Response

200

Everything worked as expected.

success

boolean

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

DELETE/v1/visitors/{id}/attributes/{attributeKey}Requires auth

#Delete a visitor attribute

#Parameters

path parameters

id

stringRequiredpath

attributeKey

stringRequiredpath

#Response

200

Everything worked as expected.

success

boolean

#Error response

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.