Events

Once you integrate your platforms through the NotifyVisitors SDK, it automatically begins tracking standard user interactions with your apps and campaigns — these are called system events.

Beyond system events, you can track custom events that are specific to your business — such as a product being added to a cart, a form submission, or a subscription upgrade. Custom events can carry event attributes like product name, order ID, total amount, category, and more. This data powers personalised campaigns across all your engagement channels.

Before You Start: Users Must Exist First

The Events API should be used to log events against existing users only. It should not be used to create users.

If you pass a userID, email, or mobile for a user that does not yet exist, the API processes the event and user creation in a single call — but not in sequential order. The event may log before the user record is created. The event does get attached to the user's profile, but many features will not work properly because the event timestamp is earlier than the user's creation timestamp.

Example: OTP Verification Journey

Say you have an automated journey triggered by a signup event, where users receive OTP verification reminders until the otp_verified goal is met. If you log the signup event for a new user through the Events API, the event shows on their profile — but its timestamp falls before the user's creation time. Since journeys only trigger for events performed after the user enters the system, the user never enters the journey and never receives any reminders. This issue is especially hard to debug because the event is clearly visible on the profile — everything looks correct, but the journey simply never fires.

The Correct Workflow

Step 1 — Create the user (and optionally log the first event together).
You have two options:

• User only — Call the Upload user profile API to create or update the user profile on its own. Use this when you only need to register the user without logging an event yet. This endpoint also supports bulk uploads (up to 100 users in a single call).
• User + Event together — Call the Create/Update User Profile and Log Event API to create or update the user and log the first event in the same call. The API processes them in the sequential order — user first, then event — so the event timestamp falls after the user's creation timestamp and journeys trigger as expected.

In both cases, if user profile merging is enabled, you can pass any one of userID, email, or mobile. If merging is disabled, userID is mandatory.

Step 2 — Log all subsequent events via the Events API.
Once the user exists, use the Events API (/api/event) for follow-up events like otp_verified, first_purchase, etc. The user record is already in the system, so all events will map correctly.

Quick Reference

API Endpoint for Tracking Events

Upload Events (batch)
Log one or more events for existing users. Supports up to 1,000 event entries per call.

POST https://event-api.notifyvisitors.com/api/event

Event Attributes Example

{
  "nv": [{
    "userID": "XYZ4421",
    "email": "[email protected]",
    "mobile": "+9198203010",
    "event_name": "Order Placed",
    "ltv": "10",
    "attributes": {
      "product_name": "Test Product",
      "order_id": 12345,
      "total_amount": 100
    },
    "context": {
      "ip_address": "",
      "language": "en-GB",   //language code
      "platform": "website",  //website, m-site, android app, ios app
      "page": {
        "url": "https://www.example.com/about",
        "referrer": "https://www.google.com",
        "query_params": "tracking=yes&code=xxxxxx",
        "landing_page_url": "https://www.example.com"
      },
      "utm": {
        "campaign": "summer_sale_2022",
        "source": "google",
        "medium": "cpc",
        "term": "running+shoes",
        "content": "banner_ad_variant_a",
        "google_click_id": "Cj0KCQjwxYZ4421abcdEFG",
        "ad_source": "google_ads",
        "adcampaign_id": "9087654321",
        "adgroup_id": "1122334455",
        "ad_id": "6677889900"
      }
    },
    "event_time": "2022-03-27 04:08:18"
  }]
}

Parameter Reference

Note: The API accepts userID, email, and mobile as user identifiers. The email and mobile fields are used for identifying users only when merging is enabled for your account. However, other user_params (profile attributes) cannot be passed through this API. User profile data must be managed via the Create/Update User Profile and Log Event API.

Points to Remember

• Event names are case-sensitive and must be under 255 characters in length.
• Event names should not contain any special characters except space, underscore, or hyphen.
• Event attribute names are also case-sensitive and must be under 50 characters in length.
• String attribute values must be under 255 characters (255 bytes) in length.
• Each event can have up to 255 properties.
• Custom event attributes support the following data types, each with its own per-event attribute limit (i.e., the maximum number of attributes of that type you can include on a single event):
  • String: up to 200 attributes
  • Number: up to 100 attributes
  • Boolean: up to 20 attributes
  • Date (including Timestamp): up to 20 attributes
  • Object: up to 20 attributes
  • Array of Objects: up to 5 attributes
• Type locking: The first value sent for an attribute establishes its data type. If you later send a different type (e.g., quantity: "five" after sending quantity: 5), those mismatched values will not flow to your NotifyVisitors dashboard. In such cases, introduce a new attribute (e.g., quantity_v2) with the correct type — do not change the original.
• Use snake_case for event names and property names (e.g., order_completed, signup_type). Names are case-sensitive and hard to rename later, so choose a durable naming scheme from the start.
• The integration code loads and initializes the NotifyVisitors SDK asynchronously, so that it does not affect the page load time of your website.
• For a detailed breakdown of data types, limits, and naming conventions, refer to the Data Structure guide.

API Response

A successful event submission returns:

{
  "response": {
    "status": "queued"
  }
}

Error Response

If a required field like userID is missing or invalid:

{
  "response": {
    "message": "Error: userId can not be empty.",
    "status": "error"
  }
}