Event Ingestion

Track events and pageviews programmatically

Overview

The Event Ingestion API allows you to track events and pageviews from your backend services, mobile apps, or any environment where the JavaScript SDK cannot be used.

The Event Ingestion API is separate from the Analytics Query API and uses different authentication. Event ingestion uses your project token, not an API key.

Base URL

All event ingestion requests should be made to the Hub service:

https://hub.vemetric.com

Authentication

Event ingestion uses your project token (not an API key). The project token is included in the request body.

Your project token can be safely used in client-side code - it only allows sending events, not reading analytics data. Find your project token in Settings > Project Settings in the dashboard.

Track Event

Request

POST https://hub.vemetric.com/e

Track a custom event or pageview.

Request Headers

Content-Type · string · required

Must be application/json

Allow-Cookies · string

Set to "true" to enable cookie-based user tracking. Defaults to "false".

When making requests from a backend, set this to "false" or omit it. Cookie-based tracking is primarily for browser environments.

Request Body

projectToken · string · required

Your project token (found in project settings).

name · string · required

Event name. Use "$pageview" for pageviews or any custom event name.

Examples: "signup", "purchase", "$pageview"

url · string

Page URL. Required for pageview events ($pageview) and outbound link events.

Example: "https://example.com/blog/article"

identifier · string

User identifier to associate this event with a specific user. Use this for server-side tracking of identified users.

Example: "user_123"

displayName · string

User display name (e.g., name or email). Used to identify users in the dashboard.

Example: "John Doe" or "[e-mail]"

customData · object

Custom event properties as key-value pairs. All values are converted to strings.

Example:

{
  "plan": "pro",
  "amount": "99.99",
  "currency": "USD"
}

userData · object

Update user properties along with the event.

Show properties

set · object

Set or update user properties. Overwrites existing values.

Example: { "plan": "pro", "email": "[e-mail]" }

setOnce · object

Set user properties only if they don’t exist. Does not overwrite existing values.

Example: { "first_signup_date": "2026-03-04" }

unset · array<string>

Remove user properties.

Example: ["temp_token", "trial_expires"]

contextId · string

Context identifier for grouping related events (e.g., a page load context).

Response

Returns 200 status code with an empty body on success.

Examples

Track Pageview

cURL

curl -X POST 'https://hub.vemetric.com/e' \
  -H 'Content-Type: application/json' \
  -H 'Allow-Cookies: false' \
  -d '{
    "projectToken": "proj_your_project_token_here",
    "name": "$pageview",
    "url": "https://example.com/blog/article",
    "identifier": "user_123",
    "displayName": "[e-mail]"
  }'

Track Custom Event

cURL

curl -X POST 'https://hub.vemetric.com/e' \
  -H 'Content-Type: application/json' \
  -H 'Allow-Cookies: false' \
  -d '{
    "projectToken": "proj_your_project_token_here",
    "name": "purchase",
    "identifier": "user_123",
    "displayName": "[e-mail]",
    "customData": {
      "plan": "pro",
      "amount": "99.99",
      "currency": "USD",
      "billing_period": "monthly"
    }
  }'

Track with User Properties

cURL

curl -X POST 'https://hub.vemetric.com/e' \
  -H 'Content-Type: application/json' \
  -H 'Allow-Cookies: false' \
  -d '{
    "projectToken": "proj_your_project_token_here",
    "name": "signup",
    "identifier": "user_123",
    "displayName": "[e-mail]",
    "customData": {
      "plan": "pro"
    },
    "userData": {
      "set": {
        "email": "[e-mail]",
        "plan": "pro"
      },
      "setOnce": {
        "signup_date": "2026-03-04"
      }
    }
  }'

Identify User

Request

POST https://hub.vemetric.com/i

Identify a user (associate anonymous activity with a known user identifier).

Request Body

projectToken · string · required

Your project token.

identifier · string · required

Unique user identifier.

displayName · string

User display name.

Example

cURL

curl -X POST 'https://hub.vemetric.com/i' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectToken": "proj_your_project_token_here",
    "identifier": "user_123",
    "displayName": "[e-mail]"
  }'

Update User Properties

Request

POST https://hub.vemetric.com/u

Update user properties without tracking an event.

Request Body

projectToken · string · required

Your project token.

displayName · string

Update user display name.

avatarUrl · string

Update user avatar URL.

data · object

User properties to update.

Show properties

set · object

Set or update properties.

setOnce · object

Set properties only if they don’t exist.

unset · array<string>

Remove properties.

Example

cURL

curl -X POST 'https://hub.vemetric.com/u' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectToken": "proj_your_project_token_here",
    "displayName": "John Doe",
    "data": {
      "set": {
        "plan": "enterprise",
        "company": "Acme Inc"
      }
    }
  }'

Special Events

Pageview Event

Event name: "$pageview"

Required fields:

• url - The page URL

Outbound Link Event

Event name: "$outbound_link"

Required fields:

• url - The current page URL
• customData.href - The outbound link URL

Error Handling

The event ingestion API returns different status codes:

• 200 - Success (event tracked)
• 202 - Accepted (identification in progress)
• 400 - Invalid request (missing required fields or validation errors)
• 500 - Server error

Validation Errors

If required fields are missing or invalid, the API returns 400 with the text "Invalid!".

Example:

# Missing 'name' field
curl -X POST 'https://hub.vemetric.com/e' \
  -H 'Content-Type: application/json' \
  -d '{"projectToken": "proj_123"}'

# Response: 400 Invalid!

Best Practices

Always include user identifier - For backend tracking, include the identifier field to associate events with users

Use consistent identifiers - Use the same identifier across all events for a user (e.g., user ID from your database)

Include display name - Set displayName to make it easier to identify users in the dashboard

Use descriptive event names - Name events clearly (e.g., "purchase_completed" instead of "event1")

Don’t track PII in event properties - Avoid including sensitive personal information in customData unless necessary

Respect bot filtering - The system automatically filters known bots. Don’t disable this unless you have a specific reason

Server-Side SDKs

For easier integration, consider using the official server-side SDKs:

• Node.js: npm install @vemetric/node
• Python: pip install vemetric
• PHP: composer require vemetric/php
• Ruby: gem install vemetric

These SDKs handle the HTTP requests and provide a cleaner API.

Related Documentation

JavaScript SDK

Client-side event tracking for web applications

Analytics Query API

Query your tracked events and analytics data