Sending events through HTTP endpoint

The Usermaven has API for direct event collection. You can use it for sending events directly from apps or backends, including historical events.

1. Obtaining server token

Log in to your Usermaven account and select your workspace. After that go to the Workspace Settings > Setup. Select Python SDK and there you will find the Server Token.

2. Sending events

To send the event to Usermaven, you will have to send the request to the following endpoint.


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

Server Token Configuration

The API_KEY.SERVER_TOKEN is constructed by combining:

API Key
Server Token

Both values can be found in: Workspace Settings > General > Server side tracking credentials

Event body

The body is JSON object.


{
  "api_key": "API_KEY", // change this with your API key
  "event_id": "",
  "event_type": "user_identify", // once the user signs in to the platform.
  "_timestamp": 1632150122000,
  // Optional: UTC timestamp in milliseconds for historical events
  "ids": {},
  "user": {
    // Required attributes
    "anonymous_id": "random_id", // Ideally, use the __eventn_id from the cookies to stitch the user activity.
    "id": "lzL24K3kYw", // Unique ID for the user in database.
    "email": "user@domain.com", // Email address for the user.
    "created_at": "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
    // Recommended attributes
    // First name and last name are shown on people pages.
    "first_name": "John",
    "last_name": "Smith",
    // Optional attributes (you can name attributes what you wish)
    "custom": {
      "plan_name": "premium"
    }
  },
  // Send company level attributes
  "company": {
    "id": "65f02acc-e104-45d9-8199-1491332d8454",
    "name": "azhar",
    "created_at": "2022-02-15T17:25:08",
    "custom": {
      "plan": "premium"
    }
  },
  "screen_resolution": "0",
  "src": "http"
  "url": "http://localhost:3000/example",
  "page_title": "Your Page Title",
  "doc_path": "/example",
  "doc_host": "localhost",
  "doc_search": "",
  "vp_size": "0",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
  "user_language": "en-US",
  "doc_encoding": "UTF-8"
}

Note: user_identify event type is required for the signed in users. Based on the user_identify event, your users will be available in our People view. Response


{ "status": "ok" }

Sending historical events

To send historical events, include the _timestamp field in your event payload. The _timestamp should be a UTC timestamp in milliseconds. This allows you to import past events with their original occurrence time.

Sending custom event attributes

If you would like to send the custom event, the only thing that is going to be changed from the above payload is event_type. For sending additional custom event attributes, you can pass the attributes in the form of event_attributes object.

Example payload


{
  "api_key": "API_KEY", // change this with your API key
  "_timestamp": 1632150122000, // Optional: UTC timestamp in milliseconds for historical events
  "event_id": "",
  "event_type": "plan_upgraded", // once the user signs in to the platform.
  // You can send event attributes as well.
  "event_attributes": {
    "amount": 100,
    "currency": "USD"
  },
  "ids": {},
  "user": {
    // Required attributes
    "anonymous_id": "random_id", // Ideally, use the __eventn_id from the cookies to stitch the user activity.
    "id": "lzL24K3kYw", // Unique ID for the user in database.
    "email": "user@domain.com", // Email address for the user.
    "created_at": "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
    // Recommended attributes
    // First name and last name are shown on people pages.
    "first_name": "John",
    "last_name": "Smith",
    // Optional attributes (you can name attributes what you wish)
    "custom": {
      "plan_name": "premium"
    }
  },
  // Send company level attributes
  "company": {
    "id": "65f02acc-e104-45d9-8199-1491332d8454",
    "name": "azhar",
    "created_at": "2022-02-15T17:25:08",
    "custom": {
      "plan": "premium"
    }
  },
  "screen_resolution": "0",
  "src": "http"
  "url": "http://localhost:3000/example",
  "page_title": "Your Page Title",
  "doc_path": "/example",
  "doc_host": "localhost",
  "doc_search": "",
  "vp_size": "0",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
  "user_language": "en-US",
  "doc_encoding": "UTF-8"
}

Response


{ "status": "ok" }

3. Bulk events

The events API also support bulk events. In case if you would like to send multiple events in a single request, you can use the following payload.

Example


 
[
  {
    "api_key":  "API_KEY", // change this with your API key
    "event_id":  "",
    "event_type":  "plan_upgraded", // once the user signs in to the platform.
    "_timestamp":  1632150122000, // Optional: UTC timestamp in milliseconds for historical events
    // You can send event attributes as well.
    "event_attributes": {
      "amount":  100,
      "currency":  "USD"
    },
    "ids": {},
    "user": {
      // Required attributes
      "anonymous_id":  "random_id" , // Ideally, use the __eventn_id from the cookies to stitch the user activity.
      "id":  "lzL24K3kYw", // Unique ID for the user in database.
      "email":  "user@domain.com", // Email address for the user.
      "created_at":  "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
      // Recommended attributes
      // First name and last name are shown on people pages.
      "first_name":  "John",
      "last_name":  "Smith",
      // Optional attributes (you can name attributes what you wish)
      "custom": {
        "plan_name":  "premium",
      },
    },
 
    // Send company level attributes
    "company": {
      "id":  "65f02acc-e104-45d9-8199-1491332d8454",
      "name":  "azhar",
      "created_at":  "2022-02-15T17:25:08",
      "custom": {
        "plan":  "premium"
      }
    },
 
    "screen_resolution":  "0",
    "src":  "http"
  },
  {
 
    "api_key":  "API_KEY", // change this with your API key
    "event_id":  "",
    "event_type":  "plan_upgraded", // once the user signs in to the platform.
    "_timestamp":  1632150123000, // Optional: UTC timestamp in milliseconds for historical events
    // You can send event attributes as well.
    "event_attributes": {
      "amount":  25,
      "currency":  "USD"
    },
 
    "ids": {},
    "user": {
      // Required attributes
      "anonymous_id":  "random_id" , // Ideally, use the __eventn_id from the cookies to stitch the user activity.
      "id":  "lzL24K3kYw", // Unique ID for the user in database.
      "email":  "user@domain.com", // Email address for the user.
      "created_at":  "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
      // Recommended attributes
      // First name and last name are shown on people pages.
      "first_name":  "John",
      "last_name":  "Smith",
      // Optional attributes (you can name attributes what you wish)
      "custom": {
        "plan_name":  "premium",
      },
    },
    // Send company level attributes
    "company": {
      "id":  "65f02acc-e104-45d9-8199-1491332d8454",
      "name":  "azhar",
      "created_at":  "2022-02-15T17:25:08",
      "custom": {
        "plan":  "premium"
      }
    },
    "screen_resolution":  "0",
    "src":  "http"
    "url":"http://localhost:3000/example",
    "page_title":"Your Page Title",
    "doc_path":"/example",
    "doc_host":"localhost",
    "doc_search":"",
    "vp_size":"0",
    "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
    "user_language":"en-US",
    "doc_encoding":"UTF-8"
  }
]

Response


{ "status": "ok" }

If you have any questions, feel free to get in touch with us at support@usermaven.com