HTTP API

Integrate Userlens directly via HTTP requests. Use this for any environment where you want direct API access instead of using the React or Next.js SDK.

Installation

No SDK required — just make HTTP requests to the Userlens API.

When to Use HTTP API

  • Other frontend frameworks (Vue, Angular, Svelte, etc.)

  • Backend event tracking (e.g., subscription changes, background jobs)

  • Mobile applications

  • Any language (Go, Rust, PHP, Python, Ruby, etc.)

  • Full control over the integration


Authentication

All API requests require your Write Code using HTTP Basic Auth.

The token must be base64 encoded in the format write_code: (with trailing colon, empty password):

const authToken = Buffer.from(`${WRITE_CODE}:`).toString('base64');

Get your Write Code from Userlens Settings.


Base URLs

Purpose
URL

Identify & Group & Track

https://events.userlens.io

Forward SDK Events

https://raw.userlens.io


Step 1: Identify Users

Sync user information with Userlens. Call this when a user signs up, logs in, or updates their profile.

Request Body Fields:

Field
Type
Required
Description

type

string

Yes

Must be "identify"

userId

string

Yes

Unique user identifier

source

string

Yes

Use "userlens-restapi"

traits

object

Yes

User properties (email, name, plan, etc.)


Step 2: Group Users (Optional)

Associate users with companies or organizations. Essential for B2B analytics.

Request Body Fields:

Field
Type
Required
Description

type

string

Yes

Must be "group"

groupId

string

Yes

Unique company/org identifier

userId

string

Yes

User being associated

source

string

Yes

Use "userlens-restapi"

traits

object

No

Company properties


Step 3: Track Events

Track custom events like purchases, feature usage, or any meaningful action.

Request Body Fields:

Field
Type
Required
Description

type

string

Yes

Must be "track"

userId

string

Yes

User who performed the action

source

string

Yes

Use "userlens-restapi"

event

string

Yes

Event name (e.g., "Subscription Upgraded")

properties

object

No

Additional event data


Common Use Cases

After User Signup

After Subscription Change

Backend Job Completion


Response Codes

Code
Meaning

200

Success

400

Invalid request body

401

Invalid or missing Write Code

500

Server error


Verify It's Working

  1. Make an identify call with a test user

  2. In Userlens, check if the user appears

  3. Make a track call and verify the event shows up


Next Steps

Last updated