Skip to main content
POST
/
v1
/
public
/
subscriber.identify
curl --location --request POST 'https://api.userorbit.com/v1/public/subscriber.identify' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "john@example.com",
  "name": "John Doe",
  "meta": {
    "plan": "pro",
    "mrr": 99,
    "role": "Product Manager",
    "team": "Acme Corp"
  }
}'

{
  "data": {
    "id": "87654321-1234-1234-1234-123456789012",
    "name": "John Doe",
    "email": "john@example.com",
    "source": "api",
    "meta": {
      "plan": "pro",
      "mrr": 99,
      "role": "Product Manager",
      "team": "Acme Corp"
    },
    "avatarUrl": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "lastUpdated": "2024-01-15T10:30:00Z"
  },
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "isFirstSignin": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.userorbit.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

This endpoint requires API key authentication via the Authorization header. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
email
string
required
Subscriber’s email address. Used as unique identifier.
​
name
string
Subscriber’s display name. If not provided, will be derived from email or existing data.
​
meta
object
Custom metadata for the subscriber

​
Response

​
data
object
Subscriber object
​
code
string
JWT token for authenticating subsequent requests as this subscriber
​
isFirstSignin
boolean
True if this is a new subscriber, false if existing
curl --location --request POST 'https://api.userorbit.com/v1/public/subscriber.identify' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "john@example.com",
  "name": "John Doe",
  "meta": {
    "plan": "pro",
    "mrr": 99,
    "role": "Product Manager",
    "team": "Acme Corp"
  }
}'

{
  "data": {
    "id": "87654321-1234-1234-1234-123456789012",
    "name": "John Doe",
    "email": "john@example.com",
    "source": "api",
    "meta": {
      "plan": "pro",
      "mrr": 99,
      "role": "Product Manager",
      "team": "Acme Corp"
    },
    "avatarUrl": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "lastUpdated": "2024-01-15T10:30:00Z"
  },
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "isFirstSignin": true
}

​
Behavior

  • Existing Subscriber: If email exists, updates metadata and returns existing subscriber
  • New Subscriber: Creates new subscriber with provided information
  • Metadata Merge: New metadata is merged with existing metadata (doesn’t overwrite completely)
  • Case Insensitive: Email matching is case-insensitive

​
Use Cases

  • Widget Initialization: Identify user when loading feedback widget
  • User Tracking: Track user activity and associate with account
  • User Segmentation: Store custom attributes for targeting
  • Personalization: Use metadata to customize user experience

​
Notes

  • The returned code (JWT token) should be stored and used for subsequent authenticated requests
  • Metadata fields are flexible - you can add any custom fields
  • Only mmr, plan, role, team, and created_at are automatically extracted from metadata
  • Email is case-insensitive and will be stored in lowercase