WysLeap
REST API · v1.0

API Documentation

Integrate WysLeap's privacy-first visitor intelligence into any application. Telemetry ingest, analytics reads, and real-time webhook events.

OpenAPI ReferenceOnboarding Guide

Quick Start

The fastest path depends on what you need:

01

Create a site

Sign up, add your site, and receive a siteId and API key instantly.

Get started
02

Add the tracker

One script tag auto-tracks pageviews, clicks, scroll depth, and session replays.

Onboarding guide
03

Call the API

Track custom events, read analytics data, and configure webhooks below.

Jump to endpoints

Overview

Base URL
https://wysleap.com/api
Authentication

API Key — header or body

Response format

JSON + HTTP status codes

Authentication

Every API request requires your API key, found in Site Settings. Supply it as a request header (recommended) or inside the request body.

Header (recommended)

http
X-API-Key: your-api-key-here

Request body

json
{
  "siteId": "your-site-id",
  "_apiKey": "your-api-key-here"
}
Security: Never expose your API key in client-side code or public repos. Use environment variables and rotate immediately if compromised.

Endpoints

POST/telemetry/pageview

Track page views. Automatically builds visitor profiles from browser and device signals.

Request Parameters

ParameterTypeRequiredDescription
siteIdstringYesYour site identifier
pageUrlstringYesFull URL of the page being viewed
pageTitlestringNoPage title from document.title
referrerstringNoReferring URL
visitorIdstringNoVisitor ID — auto-generated if omitted
sessionIdstringNoSession ID — auto-generated if omitted
screenWidthintegerNoViewport width in pixels
screenHeightintegerNoViewport height in pixels
languagestringNoBrowser language (e.g. en-US)
timeZonestringNoIANA timezone identifier
_apiKeystringYes*API key (or use X-API-Key header)

Code Examples

cURL
curl -X POST https://wysleap.com/api/telemetry/pageview \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "your-site-id",
    "pageUrl": "https://example.com/products",
    "pageTitle": "Products - Example Store",
    "referrer": "https://google.com",
    "visitorId": "vis_abc123",
    "sessionId": "sess_xyz789",
    "userAgent": "Mozilla/5.0...",
    "screenWidth": 1920,
    "screenHeight": 1080,
    "language": "en-US",
    "timeZone": "America/New_York",
    "_apiKey": "your-api-key"
  }'

Response 200 OK

json
{
  "success": true,
  "message": "Pageview tracked successfully",
  "visitorId": "vis_abc123",
  "sessionId": "sess_xyz789",
  "timestamp": "2025-01-15T10:30:00Z"
}
POST/telemetry/event

Track custom events — purchases, sign-ups, button clicks, or any meaningful interaction.

Use Title Case for event names — e.g. Sign Up Success, not sign_up_success.

Request Parameters

ParameterTypeRequiredDescription
siteIdstringYesYour site identifier
eventNamestringYesEvent name in Title Case (e.g. "Purchase Completed")
eventDataobjectNoAny JSON-serialisable metadata for the event
visitorIdstringNoVisitor ID to associate the event with
sessionIdstringNoSession ID to associate the event with
pageUrlstringNoURL where the event occurred
_apiKeystringYes*API key (or use X-API-Key header)

Code Examples

cURL
curl -X POST https://wysleap.com/api/telemetry/event \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "your-site-id",
    "eventName": "Purchase Completed",
    "eventData": {
      "productId": "prod_123",
      "productName": "Premium Plan",
      "currency": "USD"
    },
    "visitorId": "vis_abc123",
    "pageUrl": "https://example.com/checkout/success",
    "_apiKey": "your-api-key"
  }'

Response 200 OK

json
{
  "success": true,
  "message": "Event tracked successfully",
  "eventId": "evt_123456",
  "timestamp": "2025-01-15T10:30:00Z"
}
GET/visitors/{siteId}

Retrieve analytics data — visitor stats, behaviour patterns, intent scores, and page metrics.

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Number of recent visitors to return (max 1000)
daysinteger30Number of days to look back
countrystring—Filter by ISO 3166-1 alpha-2 country code

Code Examples

cURL
curl -G "https://wysleap.com/api/visitors/your-site-id" \
  -H "X-API-Key: your-api-key" \
  --data-urlencode "limit=50" \
  --data-urlencode "days=30"

Response 200 OK

json
{
  "site": {
    "totalPageviews": 15234,
    "totalEvents": 3456,
    "avgTimeOnPage": 127.5,
    "bounceRate": 0.42,
    "pageviewsByDay": [
      { "date": "2025-01-15", "views": 234 }
    ],
    "topPages": [
      { "path": "/products", "views": 1234, "avgTimeOnPage": 145.2 }
    ]
  },
  "visitors": [
    {
      "visitorId": "vis_abc123",
      "lastVisit": "2025-01-15T10:30:00Z",
      "visitCount": 5,
      "country": "United States",
      "browser": "Chrome",
      "intentScore": {
        "level": "high",
        "score": 85,
        "factors": ["Returning visitor", "High engagement"]
      },
      "accuracyMetrics": {
        "confidence": 0.92,
        "fingerprintQuality": "excellent"
      }
    }
  ],
  "uniqueVisitors": 1234,
  "activeVisitors": 23,
  "totalCountries": 45,
  "patterns": { "returningVisitorRate": 0.38 }
}

Error Handling

All error responses use standard HTTP status codes with a consistent JSON body.

400Bad Request
json
{
  "error": "Missing required field: siteId",
  "code": "VALIDATION_ERROR"
}
401Unauthorized
json
{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}
404Not Found
json
{
  "error": "Site not found",
  "code": "NOT_FOUND"
}
429Too Many Requests
json
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}
500Internal Server Error
json
{
  "error": "Internal server error",
  "code": "SERVER_ERROR"
}

Webhooks

Receive real-time HTTP POST notifications when events occur on your site. Configure endpoint URLs in Site Settings → Webhooks.

Supported Events

pageviewFired when a page view is tracked
eventFired when a custom event is tracked
visitor_identifiedFired when a new visitor is fingerprinted
high_intent_visitorFired when a visitor's intent score reaches high

Payload Structure

json
{
  "event": "pageview",
  "siteId": "your-site-id",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "pageUrl": "https://example.com/products",
    "visitorId": "vis_abc123",
    "intentScore": { "level": "high", "score": 85 }
  },
  "signature": "sha256=abc123..."
}

Signature Verification

javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  const expected = `sha256=${digest}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate Limits

Limits are applied per API key, measured in requests per minute. When exceeded the API returns 429 Too Many Requests.

Free Plan

100

requests / minute

Pro Plan

1,000

requests / minute

Business Plan

10,000

requests / minute

Response Headers

X-RateLimit-LimitYour total rate limit
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the current window resets

JavaScript SDK

The easiest integration — one script tag handles visitor identification, session management, and data collection automatically.

For full setup, configuration options (trackClicks, trackScroll, session replay), and all SDK methods (trackPageView, trackEvent, getVisitorId), see the Onboarding Guide.

Use WysLeap.trackEvent('Event Name', { }) in your app to send custom events without calling the REST endpoint directly.

Ready to get started?

Get your API key and start integrating privacy-first visitor intelligence into your application.

Get Your API Key Contact Support