Sending events through the HTTP endpoint

Usermaven provides a powerful HTTP API for direct event collection. This guide provides a comprehensive walkthrough for authenticating requests, structuring event payloads, and utilizing advanced features like identity stitching and historical import.

Getting your API credentials

To interact with the API, you need two credentials from your Usermaven workspace: an API Key and a Server Token.

1. Log in to your Usermaven account and select your workspace.

2. Navigate to Workspace Settings > Setup.

3. Select the HTTP API tab.

4. Copy both your API Key and Server Token.

Sending events: The fundamentals

Quick reference

This guide covers everything you need to send events to Usermaven:

• Required fields: api_key, event_type, and a user object with at least one identifier

• Endpoint: https://events.usermaven.com/api/v1/s2s/event?token=API_KEY.SERVER_TOKEN

• Format: Single event (JSON object) or batch events (JSON array)

• Complete field list: See Complete field reference for all available fields

API endpoint

All server-to-server events should be sent to:

https://events.usermaven.com/api/v1/s2s/event

Alternative endpoint: You can also use https://events.usermaven.com/api/v1/s2s/events (both endpoints work identically).

Authentication methods

Authentication is required for all requests. You can authenticate using any of these three methods:

1. URL query parameter (Recommended for server-to-server)

Include the authentication token in the URL query string:

https://events.usermaven.com/api/v1/s2s/event?token=API_KEY.SERVER_TOKEN

2. Authorization header

Include the API key in the Authorization header:

curl -X POST https://events.usermaven.com/api/v1/s2s/event \
  -H "Authorization: Bearer YOUR_API_KEY.YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "user_identify", "user": {"id": "usr_123"}}'

3. Request body

Include the api_key field in the JSON payload (this can be combined with query parameter or header authentication):

{
  "api_key": "YOUR_API_KEY",
  "event_type": "user_identify",
  "user": { "id": "usr_123" }
}

Note: If authentication is provided via both header/query parameter and request body, the header/query parameter value takes precedence.

Request and response formats

Content types

The API accepts two content types:

Content-Type	Description	Use Case
application/json	Standard JSON format (recommended)	Default for most integrations
application/x-www-form-urlencoded	Form data with base64-encoded data field	Legacy support

Response format

All endpoints return the same response format:

Success Response (HTTP 200):

{
  "status": 1
}

Error Responses:

HTTP Status	Description	Response Format
400 Bad Request	Invalid JSON payload or no events in batch	Error message string
401 Unauthorized	Invalid or missing API key	Error message string

Automatic data enrichment

The following data is automatically captured and enriched by Usermaven if not provided:

• IP Address: Extracted from x-forwarded-for header

• User Agent: Extracted from user-agent header

• Referrer: Extracted from referer header

• Received Timestamp: Server timestamp when event is received

• Geolocation: Enriched based on IP address

• Device Information: Browser, OS, and device type parsed from user agent

• Bot Detection: Automatic identification of bot traffic

Event payload structure

Events are sent as JSON objects in the POST request body. A well-structured payload ensures your data is processed correctly.

Core event fields

Field	Type	Required	Description
api_key	String	Yes	Your workspace-specific API Key (can also be provided via URL token or Authorization header)
event_type	String	Yes	The name of the event (e.g., user_identify, plan_upgraded, button_clicked)
user	Object	Yes	User identification and attributes object (see User Object Fields below)
event_attributes	Object	No	Custom attributes specific to this event (any key-value pairs)
company	Object	No	Company/organization information associated with the user
timestamp	Integer	No	Custom Unix timestamp in milliseconds for historical events (UTC)

User object fields

The user object is flexible and accepts any custom fields. Common and recommended fields:

Field	Type	Required	Description
id	String	Yes\*	Unique user identifier from your database
email	String	Recommended	User's email address
anonymous_id	String	Conditional\*\*	ID from browser cookie (see Identity Stitching section)
first_name	String	No	User's first name
last_name	String	No	User's last name
created_at	String	Recommended	ISO 8601 timestamp for when the user signed up
Custom fields	Any	No	Any additional user attributes as key-value pairs

\* At least one user identifier (id, email, or anonymous_id) must be provided. \*\* Required only for the first user_identify call when stitching anonymous activity (see Identity Stitching section).

Minimal example: Identifying a user

This is the most basic payload required to identify a user and create their profile.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "user_identify", // change this with your event type
  "user": {
    "id": "usr_1a2b3c4d5e", // User ID from your database
    "email": "hello@usermaven.com", // User email
    "created_at": "2023-01-20T09:55:35Z" // User signup date in ISO 8601 format
  }
}

Sending custom events with attributes

For any action other than identifying a user, use a custom event_type and add relevant details in the event_attributes object.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "plan_upgraded", // change this with your event type
  "event_attributes": {
    "plan_from": "basic",
    "plan_to": "premium",
    "amount": 100,
    "currency": "USD"
  },
  "user": {
    "id": "usr_1a2b3c4d5e" // User ID from your database
  }
}

Complete field reference

This section provides a comprehensive overview of all fields you can include in your event payloads.

Company object fields

The company object allows you to associate users with organizations. It's particularly useful for B2B applications.

Field	Type	Required	Description
id	String	No	Unique company identifier from your database
name	String	No	Company name
created_at	String	No	ISO 8601 timestamp for when the company was created
Custom fields	Any	No	Any additional company attributes (e.g., industry, size, plan_tier)

Example:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "user_identify",
  "user": {
    "id": "usr_123",
    "email": "john@acme.com"
  },
  "company": {
    "id": "comp_456",
    "name": "Acme Corporation",
    "created_at": "2020-01-15T10:00:00Z",
    "industry": "Technology",
    "size": "50-200"
  }
}

Page tracking fields

These fields help track page views and user navigation. They're automatically captured by the browser SDK but can be sent manually for server-side tracking.

Field	Type	Required	Description
url	String	No	Full URL of the page (e.g., https://example.com/pricing?plan=pro)
page_title	String	No	Title of the page
referrer	String	No	Referring URL (where the user came from)
doc_path	String	No	Document path component of the URL (e.g., /pricing)
doc_host	String	No	Document host/domain (e.g., example.com)
doc_search	String	No	Query string parameters (e.g., ?plan=pro)
doc_encoding	String	No	Document character encoding (e.g., UTF-8)

Device & browser fields

These fields provide context about the user's device and browser environment.

Field	Type	Required	Description
user_agent	String	No	User agent string (auto-captured from headers if not provided)
user_language	String	No	User's browser language (e.g., en-US)
screen_resolution	String	No	Screen resolution (e.g., 1920x1080)
vp_size	String	No	Viewport size (e.g., 1280x720)

UTM & marketing attribution fields

Track campaign performance and marketing attribution with these fields.

Field	Type	Required	Description
utm	Object	No	UTM campaign parameters object
utm.source	String	No	UTM source (e.g., google, newsletter)
utm.medium	String	No	UTM medium (e.g., cpc, email)
utm.campaign	String	No	UTM campaign name (e.g., summer_sale_2024)
utm.term	String	No	UTM term for paid search keywords
utm.content	String	No	UTM content for A/B testing and differentiating ads

Example:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "signup_completed",
  "user": {
    "id": "usr_789",
    "email": "user@example.com"
  },
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "summer_sale_2024",
    "term": "analytics software",
    "content": "ad_variant_a"
  }
}

Click ID tracking fields

Track clicks from advertising platforms with these dedicated fields.

Field	Type	Required	Description
click_id	Object	No	Click tracking IDs from various platforms
click_id.gclid	String	No	Google Click ID for Google Ads tracking
click_id.fbclid	String	No	Facebook Click ID for Facebook Ads tracking

Third-party tracking IDs

Integrate with other analytics platforms using these fields.

Field	Type	Required	Description
ids	Object	No	Various third-party tracking identifiers
ids.ga	String	No	Google Analytics ID
ids.fbp	String	No	Facebook Pixel ID
ids.ajs_anonymous_id	String	No	Segment.io anonymous ID
ids.ajs_user_id	String	No	Segment.io user ID

Technical & privacy fields

Advanced fields for technical control and privacy compliance.

Field	Type	Required	Description
source_ip	String	No	User's IP address passed in the event payload (alternative to ip field)
utc_time	String	No	UTC timestamp of when the event occurred (ISO 8601 format)
received_at	String	Auto	Server timestamp when event was received (automatically generated)
src	String	No	Source/origin identifier of the event (e.g., web, mobile, backend)
cookie_policy	String	No	Cookie consent policy status (can be passed as query parameter)
ip_policy	String	No	IP tracking policy status (can be passed as query parameter)
library	Object	No	Information about the library/SDK sending the event
library.name	String	No	Name of the library (e.g., my_backend_service)
library.version	String	No	Version of the library (e.g., 1.2.3)

Autocapture fields

These fields are automatically populated by the browser SDK when using autocapture features.

Field	Type	Required	Description
autocapture_attributes	Object	No	Automatically captured element attributes (for click events, forms, etc.)

Common field formats and examples

To ensure your events are processed correctly, follow these format guidelines:

Field	Format	Example	Notes
timestamp	Unix timestamp in milliseconds (Integer)	1632150122000	UTC time only
user.created_at	ISO 8601 string	"2023-01-20T09:55:35Z"	Include timezone
utc_time	ISO 8601 string	"2023-01-20T09:55:35Z"	Include timezone
user.id	String	"usr_1a2b3c4d5e"	Any unique identifier
user.email	String	"user@example.com"	Valid email format
screen_resolution	String	"1920x1080"	Width x Height
vp_size	String	"1280x720"	Width x Height
user_language	String	"en-US"	ISO language code
event_attributes	Object	{"amount": 100, "currency": "USD"}	Any valid JSON

Advanced event tracking

Identity stitching: Connecting anonymous and identified users

Identity stitching merges a user's activity before and after they log in into a single, unified timeline. This is achieved by passing the anonymous_id from the browser on the first server-side user_identify event type call.

When anonymous_id is required

• For the first server-side user_identify call for a user who had prior anonymous browser activity.

• When you are doing server-side-only tracking and need to manually bridge sessions.

When anonymous_id is not needed

• If the user is already identified via the usermaven("id", ...) call in the browser.

• For all subsequent server-side events after the user has been successfully identified.

• For users who sign up directly with no prior anonymous activity on your site.

Getting the anonymous_id from browser cookies

Use this helper function in your frontend code to retrieve the ID from the __eventn_id_cookie and send it to your backend.

// Helper function to get Usermaven anonymous ID from browser
function getUsermavenAnonymousId() {
  const cookie = document.cookie.split('; ').find((c) => c.startsWith('__eventn_id_'));
  return cookie ? cookie.split('=')[1] : null;
}

// Example: Send it to your backend when the user signs up
const anonId = getUsermavenAnonymousId();
// fetch('/api/signup', { body: JSON.stringify({..., anonymousId: anonId }) });

Historical import: Sending past events

To import events that occurred in the past, include the timestamp field in your payload.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "user_signup", // change this with your event type
  "timestamp": 1632150122000, // UTC timestamp in milliseconds
  "user": {
    "id": "usr_past_user_001", // User ID from your database
    "email": "historical.user@example.com", // User email
    "created_at": "2021-09-20T12:00:00Z" // User signup date in ISO 8601 format
  }
}

Bulk events: Sending multiple events at once

To improve performance, you can send a JSON array of multiple event objects in a single POST request.

[
  {
    "api_key": "YOUR_API_KEY", // change this with your API key
    "event_type": "plan_upgraded", // change this with your event name
    "timestamp": 1632150122000, // UTC timestamp in milliseconds (optional)
    "event_attributes": { "amount": 100, "currency": "USD" },
    "user": { "id": "user_123" }
  },
  {
    "api_key": "YOUR_API_KEY", // change this with your API key
    "event_type": "feature_used", // change this with your event name
    "timestamp": 1632150123000, // UTC timestamp in milliseconds (optional)
    "event_attributes": { "feature_name": "advanced_analytics" },
    "user": { "id": "user_123" }
  }
]

Best practices and testing

Creating high-quality server-side events

For the most valuable analytics, structure your payloads with these layers of information:

1. Core Event Data: The required api_key, event_type, and user object.

2. User & Company Data: Enrich the user object with email, name, and custom traits. Add a company object for B2B contexts.

3. Event-Specific Data: Use event_attributes to add custom properties relevant to the specific event.

4. Context Information: Add fields like ip, user_agent, url, and utmparameters to enrich events and improve attribution.

5. Timing Data: Include the timestamp field for historical imports or custom event timing.

Refer to the Complete field reference section above for all available fields.

Example of a comprehensive event payload:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "purchase_completed",
  "user": {
    "id": "usr_123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "company": {
    "id": "comp_456",
    "name": "Acme Corp"
  },
  "event_attributes": {
    "order_id": "order_789",
    "total_amount": 299.99,
    "currency": "USD",
    "items_count": 3
  },
  "url": "https://example.com/checkout/success",
  "page_title": "Order Confirmation",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "summer_sale"
  },
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "library": {
    "name": "my_backend_service",
    "version": "1.2.3"
  }
}

Testing and validation

Verification steps

1. Check event delivery: Go to Configure \> Events Activity in your dashboard to see events arriving in real-time.

2. View user profiles: Check Contacts Hub \> People to ensure users are being identified correctly.

3. Test identity stitching:

   • Open your site in an incognito window.

   • Browse several pages anonymously.

   • Sign up or log in, triggering your user_identify event call with the anonymous_id.

   • Check the new user's timeline in Usermaven to verify that their pre-login pageviews are correctly attributed to their profile.

Common issues and troubleshooting

• Events not appearing: Double-check that your combined token is formatted correctly (API_KEY.SERVER_TOKEN) and that your request Content-Type is application/json.

• Anonymous activity not connecting: Ensure you are successfully retrieving the anonymous_id from the cookie and including it in the first user_identify event call only.

• 400 Bad Request error: Verify your JSON payload is properly formatted and includes all required fields (api_key, event_type, user).

• 401 Unauthorized error: Confirm your API key and server token are correct and properly combined.

Key takeaways

• Always include user identification: Provide at least one user identifier (id, email, or anonymous_id)

• Use descriptive event names: Choose clear, consistent event names (e.g., signup_completed, plan_upgraded)

• Enrich with context: Add UTM parameters, page tracking fields, and custom attributes for better insights

• Batch for efficiency: Send multiple events in a single request when possible

• Test first: Always test in a development workspace before sending production data

• Leverage auto-enrichment: Many fields (IP, user agent, geolocation) are captured automatically

• Follow privacy requirements: Use cookie_policy and ip_policy fields for compliance

Additional resources

• How to send backend events using Node.js SDK

• How to send backend events using Python SDK

• How to send events from Segment CDP to Usermaven

• How to send events from any application using webhooks

• Learn more about identity resolution in Usermaven

If you have questions about implementing the Usermaven API, reach out to our support team via in-app chat or email at support@usermaven.com.