Events API Reference

#The Event object

Records each scan or workflow action Linkbreakers processes, stitching together visitor, device, link, and routing details so analytics and automations stay in sync.

action

string (enum)

The type of event action

Allowed values

ACTION_UNSPECIFIED

Action not specified

ACTION_SCAN

First-time scan or click

ACTION_RESCAN

Replay of the same device on the same link

createdAt

string (date-time)

Timestamp when the event object was created

destination

string

Final resolved destination after workflow evaluation

device

object

Tracks the fingerprint of a visitor's hardware/software so Linkbreakers can de-duplicate scans, enrich analytics, and power security heuristics.

deviceId

string

Device fingerprint associated with the event (UUID)

entrypoint

string

Entrypoint URL that received the request (short link)

httpMethod

string (enum)

The HTTP method used when the event was generated

Allowed values

HTTP_METHOD_UNSPECIFIED

HTTP method not specified

HTTP_METHOD_GET

HTTP_METHOD_POST

HTTP_METHOD_PUT

HTTP_METHOD_DELETE

HTTP_METHOD_PATCH

HTTP_METHOD_OPTIONS

HTTP_METHOD_HEAD

string

Unique identifier for the event object (UUID)

leadScore

object

Stores the AI-generated assessment Linkbreakers produces for a visitor's engagement with a link, including reasoning signals and user feedback to continuously refine scoring.

leadScoreId

string

Lead score entry computed for this visitor-link pair (UUID)

link

object

Core resource that ties a shortlink or QR entrypoint to its workflow, destination, and analytics metadata, letting Linkbreakers serve dynamic experiences while tracking scans for a workspace.

linkId

string

Identifier of the link producing the event (UUID)

scannedAt

string (date-time)

When the QR code or link was accessed

triggeredBy

string (enum)

The actor that triggered the event

Allowed values

TRIGGERED_BY_UNSPECIFIED

Trigger source not specified

TRIGGERED_BY_VISITOR

Visitor initiated the scan (as opposed to system-generated)

updatedAt

string (date-time)

Timestamp when the event object was last updated (e.g. when lead score computed)

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.

visitorId

string

Visitor profile associated with the event (UUID)

workspace

object

Serves as the tenant boundary in Linkbreakers, grouping links, members, settings, billing state, and analytics under a single organization's environment.

workspaceId

string

Identifier of the owning workspace (UUID)

Learn more

Learn more about events in Linkbreakers

Example object

{
  "action": "ACTION_SCAN",
  "createdAt": "2025-10-29T07:56:29.928Z",
  "destination": "https://brand.example.com/checkout",
  "device": {
    "browserLanguage": "en-US,en;q=0.9",
    "browserName": "Chrome",
    "browserVersion": "99.0.4844.51",
    "city": "New York",
    "country": "US",
    "createdAt": "2025-10-29T07:56:29.928Z",
    "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-29T07:56:29.928Z",
    "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-29T07:56:29.928Z",
    "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"
  },
  "deviceId": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
  "entrypoint": "https://linkbreak.ing/4BnH-R19p",
  "httpMethod": "HTTP_METHOD_GET",
  "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
  "leadScore": {
    "analysisText": "string",
    "createdAt": "2025-10-29T07:56:29.928Z",
    "educationLevel": 0,
    "engagementQuality": 0,
    "feedbackComment": "string",
    "feedbackScore": 0,
    "id": "f3fcbabe-1d52-41fb-8a3f-b6ccf7f84c9d",
    "leadScore": 0,
    "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "professionalIntent": 0,
    "recurringInterest": 0,
    "recurringScans": 0,
    "technologicalAptitude": 0,
    "updatedAt": "2025-10-29T07:56:29.928Z",
    "visitorId": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
    "wealthIndicator": 0,
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  },
  "leadScoreId": "f3fcbabe-1d52-41fb-8a3f-b6ccf7f84c9d",
  "link": {
    "createdAt": "2025-10-29T07:56:29.928Z",
    "customDomain": {
      "activatedAt": "2025-10-29T07:56:29.928Z",
      "createdAt": "2025-10-29T07:56:29.928Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2025-10-29T07:56:29.928Z",
      "name": "example.com",
      "status": "STATUS_ACTIVE",
      "updatedAt": "2025-10-29T07:56:29.928Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    },
    "customDomainId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "entrypoint": "https://linkbreak.ing/4BnH-R19p",
    "eventCount": 128,
    "fallbackDestination": "https://brand.example.com/fallback",
    "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "leadGoalDefinition": "string",
    "leadTargetDefinition": "string",
    "metadata": {},
    "name": "string",
    "qrcodeDesign": {
      "backgroundOptions": {
        "color": "string",
        "gradient": "string"
      },
      "centralImageSignedUrl": "https://example.com",
      "centralImageSize": 0,
      "cornersDotOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "cornersSquareOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "createdAt": "2025-10-29T07:56:29.928Z",
      "dotsOptions": {
        "color": "string",
        "gradient": "string",
        "type": "string"
      },
      "errorCorrectionLevel": "string",
      "height": 0,
      "hideBackgroundDots": false,
      "id": "a8c5e111-8894-4f8a-b5db-9efe0d12a210",
      "outputFileFormat": "OUTPUT_FILE_FORMAT_PNG",
      "shape": "SHAPE_SQUARE",
      "updatedAt": "2025-10-29T07:56:29.928Z",
      "width": 0
    },
    "qrcodeDesignId": "a8c5e111-8894-4f8a-b5db-9efe0d12a210",
    "qrcodePendingUpdateSince": "2025-10-29T07:56:29.928Z",
    "qrcodeSignedUrl": "https://cdn.linkbreakers.com/qrcodes/1b9d6bcd.png?signature=abc123",
    "qrcodeTemplateId": "0d7f4d9c-1aef-4ed4-821b-321a3f9cba1d",
    "shortlink": "4BnH-R19p",
    "tags": [
      {
        "createdAt": "2025-10-29T07:56:29.928Z",
        "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
        "name": "string",
        "updatedAt": "2025-10-29T07:56:29.928Z"
      }
    ],
    "updatedAt": "2025-10-29T07:56:29.928Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  },
  "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "scannedAt": "2025-10-29T07:56:29.928Z",
  "triggeredBy": "TRIGGERED_BY_VISITOR",
  "updatedAt": "2025-10-29T07:56:29.928Z",
  "visitor": {
    "attributes": {},
    "createdAt": "2025-10-29T07:56:29.928Z",
    "devices": [
      {
        "browserLanguage": "en-US,en;q=0.9",
        "browserName": "Chrome",
        "browserVersion": "99.0.4844.51",
        "city": "New York",
        "country": "US",
        "createdAt": "2025-10-29T07:56:29.928Z",
        "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-29T07:56:29.928Z",
        "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-29T07:56:29.928Z",
        "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-29T07:56:29.928Z",
        "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "scannedAt": "2025-10-29T07:56:29.928Z"
      }
    ],
    "firstName": "Sam",
    "id": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
    "lastName": "Rivera",
    "links": [
      {
        "entrypoint": "https://linkbreak.ing/4BnH-R19p",
        "eventCount": 12,
        "firstVisitedAt": "2025-10-29T07:56:29.928Z",
        "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "lastVisitedAt": "2025-10-29T07:56:29.928Z",
        "name": "Spring Launch Campaign",
        "shortlink": "4BnH-R19p"
      }
    ],
    "phone": "+15551234567",
    "updatedAt": "2025-10-29T07:56:29.928Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  },
  "visitorId": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
  "workspace": {
    "country": "string",
    "createdAt": "2025-10-29T07:56:29.928Z",
    "enforceMfa": false,
    "id": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0",
    "inactiveSince": "2025-10-29T07:56:29.928Z",
    "linkSettingId": "fbb5c4b6-2a10-4f35-8cb1-60c613a92d2a",
    "name": "string",
    "subscriptionType": "SUBSCRIPTION_TYPE_PRO_PLAN",
    "timezone": "string",
    "updatedAt": "2025-10-29T07:56:29.928Z",
    "verifiedAt": "2025-10-29T07:56:29.928Z"
  },
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}

GET/v1/eventsRequires auth

#List events

Retrieves the workspace's event timeline, returning paginated JSON by default or CSV payloads for reporting exports. For workspaces on the free plan, events older than 2 months are restricted and will not be included in the results.

#Parameters

query parameters

linkId

stringquery

Filter events to a specific link (optional, UUID) Optional

startDate

string (date-time)query

Inclusive start timestamp for the query window (workspace timezone aware). Note: For free plan workspaces, this will be automatically adjusted to not go back more than 2 months.

endDate

string (date-time)query

Inclusive end timestamp for the query window

responseFormat

stringquery

Desired response format (defaults to RESPONSE_FORMAT_JSON; use RESPONSE_FORMAT_CSV for exports)

Allowed values

RESPONSE_FORMAT_UNSPECIFIED

Response format not specified

RESPONSE_FORMAT_JSON

Response format JSON

RESPONSE_FORMAT_CSV

Response format CSV

pageSize

integer (int32)query

Maximum number of events to return (default: 100, max: 1000) Maximum number of events to return (default: 100, max: 1000)

pageToken

stringquery

Cursor token to retrieve the next page of results Cursor token to retrieve the next page of results

include

array<string>query

Optional list of relationships to include: visitor, device, link, workspace, leadScore Optional list of relationships to include: visitor, device, link, workspace, leadScore

#Response

200

Everything worked as expected.

csv

object

ListEventsCsvResponse streams the export payload when ResponseFormat is set to RESPONSE_FORMAT_CSV.

json

object

ListEventsJsonResponse returns paginated event objects suitable for 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/events?linkId={linkId}&startDate={startDate}&endDate={endDate}&responseFormat={responseFormat}&pageSize={pageSize}&pageToken={pageToken}&include={include}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "csv": {
    "contentType": "string",
    "csvData": "string"
  },
  "json": {
    "events": [
      {
        "action": "ACTION_SCAN",
        "createdAt": "2025-10-29T07:56:29.927Z",
        "destination": "https://brand.example.com/checkout",
        "device": {},
        "deviceId": "6f1b2e90-1234-4c8f-91e1-63cd927bf908",
        "entrypoint": "https://linkbreak.ing/4BnH-R19p",
        "httpMethod": "HTTP_METHOD_GET",
        "id": "8b6e1a2c-7d4f-4fd2-8b35-9a4c1f2d993a",
        "leadScore": {},
        "leadScoreId": "f3fcbabe-1d52-41fb-8a3f-b6ccf7f84c9d",
        "link": {},
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "scannedAt": "2025-10-29T07:56:29.927Z",
        "triggeredBy": "TRIGGERED_BY_VISITOR",
        "updatedAt": "2025-10-29T07:56:29.927Z",
        "visitor": {},
        "visitorId": "4da3e6a2-2d54-4b0f-9e17-4b6c2af7e9c5",
        "workspace": {},
        "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
      }
    ],
    "hasMore": false,
    "nextPageToken": "eyJwYWdlIjoxfQ==",
    "totalCount": 240
  }
}

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