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