OpenAPI Specification
openapi: 3.0.0
info:
title: Smartlook REST Events Visitors API
version: 1.0.1
description: 'The Smartlook REST API provides programmatic access to product analytics data including visitors, events, funnels, and session recordings. It supports bearer token authentication, cursor-based pagination, and regional endpoints to comply with data residency requirements.
'
contact:
url: https://integrations.smartlook.com/docs/api-overview
x-api-id: smartlook-rest-api
servers:
- url: https://api.eu.smartlook.cloud/
description: REST API - EU region
- url: https://api.us.smartlook.cloud/
description: REST API - US region
security:
- bearerAuth: []
tags:
- name: Visitors
description: Manage and query visitor data
paths:
/api/v1/visitors:
delete:
operationId: deleteVisitors
summary: Delete visitors
tags:
- Visitors
parameters:
- in: query
name: uids
schema:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
deletedItems:
type: number
additionalProperties: false
/api/v1/visitors/{visitorId}:
get:
operationId: getVisitorDetails
summary: Get visitor details
tags:
- Visitors
parameters:
- in: path
name: visitorId
schema:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
visitor:
type: object
properties:
id:
type: string
identification:
type: object
properties:
uid:
type: string
properties:
type: array
items:
$ref: '#/components/schemas/AnyValue'
additionalProperties: false
firstSeen:
type: string
lastSeen:
type: string
numberOfVisits:
type: number
numberOfSessions:
type: number
numberOfEvents:
type: number
_links:
type: object
properties:
visitorSessions:
type: string
visitorEvents:
type: string
additionalProperties: false
additionalProperties: false
additionalProperties: false
delete:
operationId: deleteVisitor
summary: Delete visitor
tags:
- Visitors
parameters:
- in: path
name: visitorId
schema:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
deletedItems:
type: number
additionalProperties: false
/api/v1/visitors/{visitorId}/sessions:
get:
operationId: getVisitorSessions
summary: Get visitor sessions
tags:
- Visitors
parameters:
- in: path
name: visitorId
schema:
type: string
required: true
- in: query
name: before
schema:
type: string
required: false
- in: query
name: after
schema:
type: string
required: false
- in: query
name: limit
schema:
type: number
required: false
- in: query
name: sort
schema:
type: string
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
totalCount:
type: number
pagination:
type: object
properties:
before:
$ref: '#/components/schemas/AnyValue'
after:
$ref: '#/components/schemas/AnyValue'
additionalProperties: false
sessions:
type: array
items:
$ref: '#/components/schemas/Session'
_links:
type: object
properties:
nextPage:
type: string
previousPage:
type: string
additionalProperties: false
additionalProperties: false
/api/v1/visitors/{visitorId}/events:
get:
operationId: getVisitorEvents
summary: Get visitor events
tags:
- Visitors
parameters:
- in: path
name: visitorId
schema:
type: string
required: true
- in: query
name: dateFrom
schema:
type: string
required: false
- in: query
name: dateTo
schema:
type: string
required: false
- in: query
name: eventTypes
schema:
type: string
required: false
description: 'What types of events should be returned in the response (values separated by ","): click, url, error, rage_click, custom, focus, text'
- in: query
name: sessionId
schema:
type: string
required: false
- in: query
name: before
schema:
type: string
required: false
- in: query
name: after
schema:
type: string
required: false
- in: query
name: limit
schema:
type: number
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
pagination:
type: object
properties:
before:
type: string
after:
type: string
additionalProperties: false
events:
type: array
items:
type: object
properties:
id:
type: string
visitorId:
type: string
sessionId:
type: string
properties:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
value:
type: string
additionalProperties: false
duration:
type: number
startedAt:
type: string
pageUrl:
type: string
type:
type: string
value:
$ref: '#/components/schemas/AnyValue'
sourceType:
type: string
eventName:
type: string
selector:
type: string
_links:
type: object
properties:
visitor:
type: string
eventVisitors:
type: string
event:
type: string
additionalProperties: false
additionalProperties: false
_links:
type: object
properties:
nextPage:
type: string
previousPage:
type: string
additionalProperties: false
additionalProperties: false
/api/v2/visitors/search:
post:
operationId: searchVisitors
summary: Search visitors
tags:
- Visitors
parameters:
- in: query
name: after
schema:
type: string
required: false
- in: query
name: limit
schema:
type: number
required: false
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: array
items:
type: object
properties:
name:
type: string
operator:
type: string
value:
oneOf:
- type: number
- type: string
- type: array
items:
type: string
additionalProperties: false
required:
- name
- operator
- value
sort:
type: object
properties:
timeCreate:
type: string
timeUpdate:
type: string
additionalProperties: false
additionalProperties: false
required:
- filters
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
totalVisitorsCount:
type: number
visitors:
type: array
items:
type: object
properties:
id:
type: string
identification:
type: object
properties:
uid:
type: string
properties:
type: array
items:
$ref: '#/components/schemas/AnyValue'
additionalProperties: false
firstSeen:
type: string
lastSeen:
type: string
_links:
type: object
properties:
visitorSessions:
type: string
visitorEvents:
type: string
additionalProperties: false
additionalProperties: false
pagination:
type: object
properties:
after:
$ref: '#/components/schemas/AnyValue'
additionalProperties: false
_links:
type: object
properties:
nextPage:
type: string
additionalProperties: false
additionalProperties: false
components:
schemas:
Session:
type: object
properties:
id:
type: string
visitorId:
type: string
identification:
type: object
properties:
uid:
type: string
properties:
$ref: '#/components/schemas/AnyValue'
visitorIp:
type: string
browser:
type: object
properties:
name:
type: string
code:
type: string
userAgent:
type: string
additionalProperties: false
platform:
type: object
properties:
name:
type: string
operatingSystem:
type: string
code:
type: string
additionalProperties: false
country:
type: object
properties:
name:
type: string
code:
type: string
region:
type: string
city:
type: string
additionalProperties: false
device:
type: object
properties:
type:
type: string
orientation:
type: string
width:
type: number
height:
type: number
additionalProperties: false
additionalProperties: false
duration:
type: number
startedAt:
type: string
endedAt:
type: string
referrer:
type: string
landingPage:
type: string
exitPage:
type: string
pageUrl:
type: array
items:
type: string
notes:
type: array
items:
type: object
properties:
id:
type: string
time:
type: number
text:
type: string
additionalProperties: false
domain:
type: string
protocol:
type: string
dashboardURL:
type: string
_links:
type: object
properties:
visitor:
type: string
sessionEvents:
type: string
additionalProperties: false
additionalProperties: false
AnyValue:
description: Can be any value - string, number, boolean, array or object.
nullable: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer