Visitors API Reference

#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

object

Arbitrary attributes provided without "$" prefix (stored as JSON object)

createdAt

string (date-time)

Timestamps

devices

array<object>

Device information collected during visitor interactions

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

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"

updatedAt

string (date-time)

workspaceId

string

Workspace that owns this visitor (UUID)

Learn more

Learn more about visitor profiles in Linkbreakers.

Example object

{
  "attributes": {},
  "createdAt": "2025-10-29T08:05:14.672Z",
  "devices": [
    {
      "browserLanguage": "en-US,en;q=0.9",
      "browserName": "Chrome",
      "browserVersion": "99.0.4844.51",
      "city": "New York",
      "country": "US",
      "createdAt": "2025-10-29T08:05:14.672Z",
      "deviceBrand": "Apple",
      "deviceConcurrency": 4,
      "deviceMemory": 6,
      "deviceName": "iPhone 14 Pro",
      "deviceType": "DEVICE_TYPE_MOBILE",
      "gpu": "Apple GPU",
      "id": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
      "ipAddress": "203.0.113.42",
      "lastUsedAt": "2025-10-29T08:05:14.672Z",
      "networkBandwidth": 10,
      "networkConnection": "4g",
      "networkRtt": 50,
      "platformName": "macOS",
      "platformVersion": "10.15.7",
      "region": "CRF",
      "screenHeight": 1117,
      "screenRatio": 1.55,
      "screenWidth": 1728,
      "state": "NY",
      "timezone": "Europe/London",
      "touchScreen": true,
      "updatedAt": "2025-10-29T08:05:14.672Z",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1"
    }
  ],
  "email": "sam.visitor@example.com",
  "events": [
    {
      "action": "SCAN",
      "createdAt": "2025-10-29T08:05:14.672Z",
      "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
      "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "scannedAt": "2025-10-29T08:05:14.672Z"
    }
  ],
  "firstName": "Sam",
  "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
  "lastName": "Rivera",
  "links": [
    {
      "entrypoint": "https://linkbreak.ing/4BnH-R19p",
      "eventCount": 12,
      "firstVisitedAt": "2025-10-29T08:05:14.672Z",
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "lastVisitedAt": "2025-10-29T08:05:14.672Z",
      "name": "Spring Launch Campaign",
      "shortlink": "4BnH-R19p"
    }
  ],
  "phone": "+15551234567",
  "updatedAt": "2025-10-29T08:05:14.672Z",
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}

GET/v1/visitorsRequires auth

#List visitors

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

#Parameters

query parameters

pageSize

integer (int32)query

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

pageToken

stringquery

Cursor token to retrieve the next page of results

stringquery

optional exact match filter

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

#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.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/visitors?pageSize={pageSize}&pageToken={pageToken}&email={email}&search={search}&include={include}&linkId={linkId}&responseFormat={responseFormat}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "csv": {
    "contentType": "string",
    "csvData": "string"
  },
  "json": {
    "hasMore": false,
    "nextPageToken": "eyJ2aXNpdG9ySWQiOiI0ZGEzIn0=",
    "totalCount": 128,
    "visitors": [
      {
        "attributes": {},
        "createdAt": "2025-10-29T08:05:14.659Z",
        "devices": [],
        "email": "sam.visitor@example.com",
        "events": [],
        "firstName": "Sam",
        "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
        "lastName": "Rivera",
        "links": [],
        "phone": "+15551234567",
        "updatedAt": "2025-10-29T08:05:14.659Z",
        "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
      }
    ]
  }
}

Base URL: https://api.linkbreakers.com

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

stringRequiredpath

Visitor identifier (UUID)

query parameters

include

array<string>query

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

#Response

200

Everything worked as expected.

attributes

object

Arbitrary attributes provided without "$" prefix (stored as JSON object)

createdAt

string (date-time)

Timestamps

devices

array<object>

Device information collected during visitor interactions

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

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"

updatedAt

string (date-time)

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.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/visitors/{id}?include={include}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "attributes": {},
  "createdAt": "2025-10-29T08:05:14.659Z",
  "devices": [
    {
      "browserLanguage": "en-US,en;q=0.9",
      "browserName": "Chrome",
      "browserVersion": "99.0.4844.51",
      "city": "New York",
      "country": "US",
      "createdAt": "2025-10-29T08:05:14.659Z",
      "deviceBrand": "Apple",
      "deviceConcurrency": 4,
      "deviceMemory": 6,
      "deviceName": "iPhone 14 Pro",
      "deviceType": "DEVICE_TYPE_MOBILE",
      "gpu": "Apple GPU",
      "id": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
      "ipAddress": "203.0.113.42",
      "lastUsedAt": "2025-10-29T08:05:14.659Z",
      "networkBandwidth": 10,
      "networkConnection": "4g",
      "networkRtt": 50,
      "platformName": "macOS",
      "platformVersion": "10.15.7",
      "region": "CRF",
      "screenHeight": 1117,
      "screenRatio": 1.55,
      "screenWidth": 1728,
      "state": "NY",
      "timezone": "Europe/London",
      "touchScreen": true,
      "updatedAt": "2025-10-29T08:05:14.659Z",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1"
    }
  ],
  "email": "sam.visitor@example.com",
  "events": [
    {
      "action": "SCAN",
      "createdAt": "2025-10-29T08:05:14.659Z",
      "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
      "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "scannedAt": "2025-10-29T08:05:14.659Z"
    }
  ],
  "firstName": "Sam",
  "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
  "lastName": "Rivera",
  "links": [
    {
      "entrypoint": "https://linkbreak.ing/4BnH-R19p",
      "eventCount": 12,
      "firstVisitedAt": "2025-10-29T08:05:14.659Z",
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "lastVisitedAt": "2025-10-29T08:05:14.659Z",
      "name": "Spring Launch Campaign",
      "shortlink": "4BnH-R19p"
    }
  ],
  "phone": "+15551234567",
  "updatedAt": "2025-10-29T08:05:14.659Z",
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}

Base URL: https://api.linkbreakers.com

POST/v1/visitor/identifyRequires auth

#Identify visitor

Finds or creates a visitor profile from an LBID and merges the provided system fields and attributes.

#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.

Example request (cURL)

curl -X POST "https://api.linkbreakers.com/v1/visitor/identify" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"lbid":"string","setOnce":false,"visitor":{"data":{}}}'

Sample payload (application/json)

{
  "lbid": "string",
  "setOnce": false,
  "visitor": {
    "data": {}
  }
}

Typical response

{
  "created": false,
  "visitor": {
    "attributes": {},
    "createdAt": "2025-10-29T08:05:14.659Z",
    "devices": [
      {
        "browserLanguage": "en-US,en;q=0.9",
        "browserName": "Chrome",
        "browserVersion": "99.0.4844.51",
        "city": "New York",
        "country": "US",
        "createdAt": "2025-10-29T08:05:14.659Z",
        "deviceBrand": "Apple",
        "deviceConcurrency": 4,
        "deviceMemory": 6,
        "deviceName": "iPhone 14 Pro",
        "deviceType": "DEVICE_TYPE_MOBILE",
        "gpu": "Apple GPU",
        "id": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
        "ipAddress": "203.0.113.42",
        "lastUsedAt": "2025-10-29T08:05:14.659Z",
        "networkBandwidth": 10,
        "networkConnection": "4g",
        "networkRtt": 50,
        "platformName": "macOS",
        "platformVersion": "10.15.7",
        "region": "CRF",
        "screenHeight": 1117,
        "screenRatio": 1.55,
        "screenWidth": 1728,
        "state": "NY",
        "timezone": "Europe/London",
        "touchScreen": true,
        "updatedAt": "2025-10-29T08:05:14.659Z",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1"
      }
    ],
    "email": "sam.visitor@example.com",
    "events": [
      {
        "action": "SCAN",
        "createdAt": "2025-10-29T08:05:14.659Z",
        "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "scannedAt": "2025-10-29T08:05:14.659Z"
      }
    ],
    "firstName": "Sam",
    "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
    "lastName": "Rivera",
    "links": [
      {
        "entrypoint": "https://linkbreak.ing/4BnH-R19p",
        "eventCount": 12,
        "firstVisitedAt": "2025-10-29T08:05:14.659Z",
        "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "lastVisitedAt": "2025-10-29T08:05:14.659Z",
        "name": "Spring Launch Campaign",
        "shortlink": "4BnH-R19p"
      }
    ],
    "phone": "+15551234567",
    "updatedAt": "2025-10-29T08:05:14.659Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}

Base URL: https://api.linkbreakers.com

PATCH/v1/visitors/{id}Requires auth

#Update a visitor

Applies partial attribute updates to an existing visitor profile.

#Parameters

path parameters

stringRequiredpath

Visitor identifier (UUID)

#Request body

visitor

object

#Response

200

Everything worked as expected.

attributes

object

Arbitrary attributes provided without "$" prefix (stored as JSON object)

createdAt

string (date-time)

Timestamps

devices

array<object>

Device information collected during visitor interactions

string

from "$email"

events

array<object>

Events associated with this visitor

firstName

string

from "$firstName" (optional)

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"

updatedAt

string (date-time)

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.

Example request (cURL)

curl -X PATCH "https://api.linkbreakers.com/v1/visitors/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"visitor":{"data":{}}}'

Sample payload (application/json)

{
  "visitor": {
    "data": {}
  }
}

Typical response

{
  "attributes": {},
  "createdAt": "2025-10-29T08:05:14.659Z",
  "devices": [
    {
      "browserLanguage": "en-US,en;q=0.9",
      "browserName": "Chrome",
      "browserVersion": "99.0.4844.51",
      "city": "New York",
      "country": "US",
      "createdAt": "2025-10-29T08:05:14.659Z",
      "deviceBrand": "Apple",
      "deviceConcurrency": 4,
      "deviceMemory": 6,
      "deviceName": "iPhone 14 Pro",
      "deviceType": "DEVICE_TYPE_MOBILE",
      "gpu": "Apple GPU",
      "id": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
      "ipAddress": "203.0.113.42",
      "lastUsedAt": "2025-10-29T08:05:14.659Z",
      "networkBandwidth": 10,
      "networkConnection": "4g",
      "networkRtt": 50,
      "platformName": "macOS",
      "platformVersion": "10.15.7",
      "region": "CRF",
      "screenHeight": 1117,
      "screenRatio": 1.55,
      "screenWidth": 1728,
      "state": "NY",
      "timezone": "Europe/London",
      "touchScreen": true,
      "updatedAt": "2025-10-29T08:05:14.659Z",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1"
    }
  ],
  "email": "sam.visitor@example.com",
  "events": [
    {
      "action": "SCAN",
      "createdAt": "2025-10-29T08:05:14.659Z",
      "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
      "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "scannedAt": "2025-10-29T08:05:14.659Z"
    }
  ],
  "firstName": "Sam",
  "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
  "lastName": "Rivera",
  "links": [
    {
      "entrypoint": "https://linkbreak.ing/4BnH-R19p",
      "eventCount": 12,
      "firstVisitedAt": "2025-10-29T08:05:14.659Z",
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "lastVisitedAt": "2025-10-29T08:05:14.659Z",
      "name": "Spring Launch Campaign",
      "shortlink": "4BnH-R19p"
    }
  ],
  "phone": "+15551234567",
  "updatedAt": "2025-10-29T08:05:14.659Z",
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}

Base URL: https://api.linkbreakers.com

DELETE/v1/visitors/{id}Requires auth

#Delete a visitor

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

#Parameters

path parameters

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.

Example request (cURL)

curl -X DELETE "https://api.linkbreakers.com/v1/visitors/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "success": false
}

Base URL: https://api.linkbreakers.com

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

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.

Example request (cURL)

curl -X DELETE "https://api.linkbreakers.com/v1/visitors/{id}/attributes/{attributeKey}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "success": false
}

Base URL: https://api.linkbreakers.com