WysLeap API Documentation

Comprehensive REST API for integrating privacy-first visitor intelligence into your applications

RESTful API

Real-time Data

Webhook Support

Quick Start

Get started in minutes with our JavaScript SDK or use our REST API directly. Choose the integration method that works best for your stack.

JavaScript SDK (Recommended)

<script src="https://wysleap.com/telemetry.js"></script>
<script>
  WysLeap.init({
    siteId: 'your-site-id',
    options: {
      _apiKey: 'your-api-key',
      trackClicks: true,
      privacy: true
    }
  });
</script>

REST API

curl -X POST https://wysleap.com/api/telemetry/pageview \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "your-site-id",
    "pageUrl": "https://example.com",
    "_apiKey": "your-api-key"
  }'

Base URL

https://wysleap.com/api

Authentication

API Key in header or request body

Response Format

JSON with consistent structure

Authentication

All API requests require authentication. You can provide your API key either in the request header or in the request body. The API key is generated when you create a site and can be found in your site settings.

Method 1: Header (Recommended)

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

Include this header in all API requests

Method 2: Request Body

{
  "siteId": "your-site-id",
  "_apiKey": "your-api-key-here",
  // ... other fields
}

Include _apiKey in the request body

Security Best Practices

Never expose your API key in client-side code or public repositories
Use environment variables to store API keys
Rotate your API key if it's been compromised
Use HTTPS for all API requests

API Endpoints

POST/telemetry/pageviewTrack page views

Track page views to monitor visitor behavior and navigation patterns. This endpoint automatically collects browser and device information to build comprehensive visitor profiles.

Request Parameters

Parameter	Type	Required	Description
siteId	string	Yes	Your site identifier
pageUrl	string	Yes	Full URL of the page
pageTitle	string	No	Page title from document.title
referrer	string	No	Referrer URL
visitorId	string	No	Unique visitor identifier (auto-generated if not provided)
_apiKey	string	Yes*	Your API key (or use X-API-Key header)

Code Examples

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"
  }'

Success Response

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

POST/telemetry/eventTrack custom events

Track custom events to monitor specific user actions like button clicks, form submissions, purchases, or any other meaningful interactions on your site.

Request Parameters

Parameter	Type	Required	Description
siteId	string	Yes	Your site identifier
eventName	string	Yes	Name of the event (e.g., "purchase_completed", "button_click")
eventData	object	No	Additional event metadata (any JSON-serializable object)
_apiKey	string	Yes*	Your API key (or use X-API-Key header)

Code Examples

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",
      "price": 99.99,
      "currency": "USD",
      "category": "subscription"
    },
    "visitorId": "vis_abc123",
    "sessionId": "sess_xyz789",
    "pageUrl": "https://example.com/checkout/success",
    "_apiKey": "your-api-key"
  }'

Success Response

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

GET/visitors/{siteId}Retrieve analytics data

Retrieve comprehensive analytics data for your site, including visitor statistics, behavior patterns, intent scores, and accuracy metrics.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of recent visitors to return (max 1000)
days	integer	30	Number of days to look back
country	string	-	Filter by country code (ISO 3166-1 alpha-2)

Code Examples

curl -X GET "https://wysleap.com/api/visitors/your-site-id?limit=50&days=30" \
  -H "X-API-Key: your-api-key"

Response Example

{
  "site": {
    "totalPageviews": 15234,
    "totalEvents": 3456,
    "avgTimeOnPage": 127.5,
    "bounceRate": 0.42,
    "pageviewsByDay": [
      { "date": "2025-01-15", "views": 234 },
      { "date": "2025-01-14", "views": 198 }
    ],
    "topPages": [
      { "path": "/products", "views": 1234, "avgTimeOnPage": 145.2 },
      { "path": "/about", "views": 567, "avgTimeOnPage": 89.3 }
    ]
  },
  "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", "Recent activity"]
      },
      "accuracyMetrics": {
        "confidence": 0.92,
        "fingerprintQuality": "excellent"
      }
    }
  ],
  "uniqueVisitors": 1234,
  "activeVisitors": 23,
  "totalCountries": 45,
  "patterns": {
    "returningVisitorRate": 0.38
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. All error responses include a descriptive error message.

400 Bad Request

Invalid request parameters or missing required fields.

{
  "error": "Missing required field: siteId",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized

Invalid or missing API key.

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

404 Not Found

Site not found or endpoint doesn't exist.

{
  "error": "Site not found",
  "code": "NOT_FOUND"
}

429 Too Many Requests

Rate limit exceeded. Check your plan limits.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

500 Internal Server Error

Server error. Please try again later or contact support.

{
  "error": "Internal server error",
  "code": "SERVER_ERROR"
}

Webhooks

Configure webhooks to receive real-time notifications when events occur on your site. Webhooks are perfect for integrating with third-party services, triggering automated workflows, or building custom analytics dashboards.

Supported Events

pageview

Triggered when a page view is tracked

event

Triggered when a custom event is tracked

visitor_identified

Triggered when a new visitor is identified

high_intent_visitor

Triggered when a visitor's intent score reaches high

Webhook Payload Structure

{
  "event": "pageview",
  "siteId": "your-site-id",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "pageUrl": "https://example.com/products",
    "pageTitle": "Products",
    "visitorId": "vis_abc123",
    "sessionId": "sess_xyz789",
    "country": "United States",
    "browser": "Chrome",
    "intentScore": {
      "level": "high",
      "score": 85
    }
  },
  "signature": "sha256=abc123..." // HMAC signature for verification
}

Webhook Security

All webhook payloads include an HMAC SHA-256 signature in the signature header. Verify this signature to ensure the webhook is from WysLeap:

// Node.js example
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 expectedSignature = `sha256=${digest}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Note: Configure webhooks in your site settings dashboard. You can set multiple webhook URLs and filter by event types.

Rate Limits

Rate limits are applied per API key to ensure fair usage and system stability. Limits are measured in requests per minute.

Free Plan

100

requests/minute

Pro Plan

1,000

requests/minute

Business Plan

10,000

requests/minute

Rate Limit Headers

All API responses include rate limit information in headers:

X-RateLimit-Limit: Your rate limit
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets

JavaScript SDK

The easiest way to integrate WysLeap is using our JavaScript SDK. It automatically handles visitor identification, session management, and data collection.

Installation

<!-- Add to your HTML <head> or before closing </body> -->
<script src="https://wysleap.com/telemetry.js"></script>
<script>
  WysLeap.init({
    siteId: 'your-site-id',
    options: {
      _apiKey: 'your-api-key',
      trackClicks: true,      // Automatically track click events
      privacy: true,          // Enable privacy mode (anonymize IP)
      disableBeacon: false    // Use sendBeacon for better reliability
    }
  });
</script>

SDK Methods

WysLeap.trackPageView()

Manually track a page view

WysLeap.trackPageView();

WysLeap.trackEvent(name, data)

Track a custom event

WysLeap.trackEvent('button_click', {
  buttonId: 'signup',
  location: 'header'
});

WysLeap.getVisitorId()

Get the current visitor ID

const visitorId = WysLeap.getVisitorId();
console.log('Visitor ID:', visitorId);

Ready to Get Started?

Get your API key and start integrating WysLeap into your application. Join thousands of developers using privacy-first visitor intelligence.

Get Your API Key Contact Support