Logo of linkbreakers
← 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

Captures the cross-link profile Linkbreakers builds for someone who scans or clicks, combining reserved identity fields, attributed devices, events, and custom traits gathered from forms.

attributes

array<object>

Arbitrary attributes provided without "$" prefix, with the type each value was captured as.

createdAt

string (date-time)

Timestamps

deviceCount

string (int64)

Number of devices attributed to this visitor

devices

array<object>

Device information collected during visitor interactions

email

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

id

string

Unique ID (UUID)

lastName

string

from "$lastName" (optional)

links

array<object>

Links associated with this visitor via events (included only on demand)

phone

string

from "$phone"

qrcodeCount

string (int64)

Number of distinct QR codes / links this visitor has interacted with

updatedAt

string (date-time)

visitCount

string (int64)

Total number of events (visits) recorded for this visitor

workspaceId

string

Workspace that owns this visitor (UUID)

GET/v1/visitorsRequires auth

#List visitors

Returns a paginated collection of visitors with optional filters, includes, and CSV export.

#Parameters

query parameters

pageSize

integer (int64)query

Maximum number of visitors to return (default 50, max 200)

pageToken

stringquery

Cursor token to retrieve the next page of results

email

stringquery

optional exact match filter

search

stringquery

optional fuzzy search across known fields

include

array<string>query

linkId

stringquery

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

responseFormat

stringquery

- RESPONSE_FORMAT_UNSPECIFIED: Response format not specified - RESPONSE_FORMAT_JSON: Response format JSON - RESPONSE_FORMAT_CSV: Response format CSV

Allowed values
RESPONSE_FORMAT_UNSPECIFIED

Response format not specified

RESPONSE_FORMAT_JSON

Response format JSON

RESPONSE_FORMAT_CSV

Response format CSV

sortField

stringquery

Field to sort by. Defaults to created_at (newest first).

Allowed values
VISITOR_SORT_FIELD_UNSPECIFIED

Sort field not specified (defaults to created_at)

VISITOR_SORT_FIELD_CREATED_AT

Sort by the date the visitor was first seen

VISITOR_SORT_FIELD_VISIT_COUNT

Sort by total number of visits (events)

VISITOR_SORT_FIELD_DEVICE_COUNT

Sort by number of attributed devices

VISITOR_SORT_FIELD_QRCODE_COUNT

Sort by number of distinct QR codes interacted with

sortDirection

stringquery

Sort direction. Defaults to descending.

Allowed values
SORT_DIRECTION_UNSPECIFIED

Sort direction not specified (defaults to descending)

SORT_DIRECTION_ASC

Sort in ascending order

SORT_DIRECTION_DESC

Sort in descending order

#Response

200

Everything worked as expected.

csv

object

ListVisitorsCsvResponse carries the raw CSV when ResponseFormat is set to RESPONSE_FORMAT_CSV.

json

object

ListVisitorsJsonResponse is the default structured payload used by dashboards.

#Error response

400-599

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

Retrieves a visitor profile by ID with optional devices, events, or links included.

#Parameters

path parameters

id

stringRequiredpath

Visitor identifier (UUID)

query parameters

include

array<string>query

Optional relationships to hydrate ("devices", "events", "links")

#Response

200

Everything worked as expected.

attributes

array<object>

Arbitrary attributes provided without "$" prefix, with the type each value was captured as.

createdAt

string (date-time)

Timestamps

deviceCount

string (int64)

Number of devices attributed to this visitor

devices

array<object>

Device information collected during visitor interactions

email

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

id

string

Unique ID (UUID)

lastName

string

from "$lastName" (optional)

links

array<object>

Links associated with this visitor via events (included only on demand)

phone

string

from "$phone"

qrcodeCount

string (int64)

Number of distinct QR codes / links this visitor has interacted with

updatedAt

string (date-time)

visitCount

string (int64)

Total number of events (visits) recorded for this visitor

workspaceId

string

Workspace that owns this visitor (UUID)

#Error response

400-599

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

error

objectRequired

Wrapped error response.

GET/v1/visitors/attributesRequires auth

#List visitor attribute keys

Returns the distinct visitor attribute keys available in the workspace or scoped to a single link.

#Parameters

query parameters

linkId

stringquery

Optional link identifier (UUID). When set, returns keys observed on visitors who interacted with this link.

#Response

200

Everything worked as expected.

attributeKeys

array<string>

Distinct selectable visitor attribute keys, including reserved system fields such as $email and $phone.

#Error response

400-599

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

Identifies a visitor from an LBID. Anonymous visitors (created at scan time) are promoted or merged into existing identified visitors. If the identity matches an existing visitor, devices and events converge into that source-of-truth record.

#Parameters

This endpoint does not accept any parameters.

#Request body

lbid

string

LBID (base64 encoded event ID) that initiated the visit (click/scan)

setOnce

boolean

If true, only set fields that are empty (set-once semantics); defaults to false (merge/overwrite)

visitor

object

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

#Response

200

Everything worked as expected.

created

boolean

Indicates whether a new visitor profile was created as part of the identification

visitor

object

Captures the cross-link profile Linkbreakers builds for someone who scans or clicks, combining reserved identity fields, attributed devices, events, and custom traits gathered from forms.

#Error response

400-599

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

Applies partial attribute updates to an existing visitor profile.

#Parameters

path parameters

id

stringRequiredpath

Visitor identifier (UUID)

#Request body

visitor

object

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

#Response

200

Everything worked as expected.

attributes

array<object>

Arbitrary attributes provided without "$" prefix, with the type each value was captured as.

createdAt

string (date-time)

Timestamps

deviceCount

string (int64)

Number of devices attributed to this visitor

devices

array<object>

Device information collected during visitor interactions

email

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

id

string

Unique ID (UUID)

lastName

string

from "$lastName" (optional)

links

array<object>

Links associated with this visitor via events (included only on demand)

phone

string

from "$phone"

qrcodeCount

string (int64)

Number of distinct QR codes / links this visitor has interacted with

updatedAt

string (date-time)

visitCount

string (int64)

Total number of events (visits) recorded for this visitor

workspaceId

string

Workspace that owns this visitor (UUID)

#Error response

400-599

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

Removes a visitor profile and its stored attributes from the workspace.

#Parameters

path parameters

id

stringRequiredpath

Visitor identifier to remove (UUID)

#Response

200

Everything worked as expected.

success

boolean

Indicates whether the visitor record was deleted

#Error response

400-599

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

Deletes a single attribute from the visitor profile without affecting other data.

#Parameters

path parameters

id

stringRequiredpath

Visitor identifier whose attribute should be removed (UUID)

attributeKey

stringRequiredpath

Attribute key to delete (without "$" prefix)

#Response

200

Everything worked as expected.

success

boolean

Indicates whether the attribute was removed

#Error response

400-599

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

error

objectRequired

Wrapped error response.