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:

Response format

All endpoints return the same response format:

Success Response (HTTP 200):

{
  "status": 1
}

Error Responses:

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

User object fields

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

* 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.

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.

Device & browser fields

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

UTM & marketing attribution fields

Track campaign performance and marketing attribution with these fields.

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.

Third-party tracking IDs

Integrate with other analytics platforms using these fields.

Technical & privacy fields

Advanced fields for technical control and privacy compliance.

Autocapture fields

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

Common field formats and examples

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

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 utm parameters 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.