REST API Overview

The Audiencelab REST API provides direct HTTP endpoints for server-to-server integration. Use these endpoints when you need maximum flexibility or when working with languages without an official SDK.

Base URL

All API requests should be made to your assigned base URL. The React Web SDK uses:

https://analytics.geeklab.app

If your organization was provisioned a different base URL, use that value instead.

API Flow Overview

The REST API follows a specific flow for tracking user events. Understanding when to call each endpoint is crucial for accurate attribution and analytics.

SDK-Aligned Flow

┌─────────────────┐     ┌────────────────────┐     ┌──────────────────────┐
│  App Initialize │ ──> │ Fetch Token        │ ──> │ Send Webhook Events  │
│ (API key ready) │     │ (device-metrics)   │     │ (retention/custom)   │
└─────────────────┘     └────────────────────┘     └──────────────────────┘

Fetch Token - Send device metrics and receive a token
Send Webhook Events - Post retention and custom events using /webhook

Optional Checks

Verify Token - Validate a token when needed
Check Data Collection Status - Verify collection is enabled for the API key

Available Endpoints

Endpoint	Method	Description	When to Call
`/fetch-token`	POST	Send device metrics and receive a token	On app init (cache the token)
`/verify-token`	POST	Verify a token	When you need to validate a token
`/check-data-collection-status`	GET	Check if data collection is enabled	On startup or diagnostics
`/webhook`	POST	Send retention, purchase, ad, or custom events	During sessions and user actions

Request Format

All requests must:

Include Content-Type: application/json header (except for GET)
Include geeklab-api-key header with your API key
Send JSON-encoded body for POST requests

Example Request Structure

curl -X POST https://analytics.geeklab.app/fetch-token \
  -H "Content-Type: application/json" \
  -H "geeklab-api-key: your_api_key" \
  -d '{
    "type": "device-metrics",
    "created_at": "2024-10-10T10:15:00.000Z",
    "data": {
      "device_name": "MacBook Pro",
      "device_model": "MacBookPro18,3",
      "os_system": "macOS 14.5",
      "timezone": "America/Los_Angeles"
    }
  }'

Response Format

All successful responses return JSON with a 200 OK status. For example, /fetch-token responds with a token:

{
  "token": "abc123def456"
}

Error responses include an error message:

{
  "error": "Error description"
}

Quick Start

Get your API key from the Audiencelab dashboard
Fetch a token using /fetch-token (cache it)
Send a retention event using /webhook
Track purchases and ad views as they occur via /webhook

Continue to Authentication to learn about API authentication.

On this page