How to send events via API

You are here:
Estimated reading time: 1 min

Please check our API Overview before continuing.

User endpoint base is event/ so for version 1 of our API you will use:

Request format:

For this endpoint you will need to pass 2 objects: user and event.

Both are mandatory and have the following structure:

  • User: object with email or _id as identifier.
  • Event: same format as Javascript event

Create new event [POST]

Request example:
 "user": {"email": "[email protected]"}
 "event": {"update": {"firstname": "alexandru"} }

Note that user must exist in the database beforehand. Otherwise you will receive an error.

Sending generic events:

Request example:
 "user": {"email": "[email protected]"}
 "event": {"generic": {"generic": {"event_name": "my_event", "firstname": "alexandru"} } }

Responses examples:

Response (HTTP status code: 200)

  "results": {
    "message": "Event created",
    "email": "Event was created for the specified user"

Response (HTTP status code: 400)

  "errors": [
      "message": "Missing event information",
      "description": "Please send event information along with user",

How to test:

  1. Make request using your desired programming language. You can test using an app like Postman.
  2. Make sure received response has a 200 status code.
  3. Wait a little and check user profile and see if event was saved on it’s profile

Events restrictions

Each of the standard events are there because are most common across industries. We continue to add “standard” events based on various integrations with new channels or new types of businesses.

Some of those have some restrictions and determine our systems to act accordingly:

Events generated by bots

By default we do our best to identify bots from real human web traffic. This is done automatically on the client side and no events identified from bots are being sent to the system. Our approach is a light one, in order not to reject real events.

Update & Login Events

Both can be used to update user attributes, by sending them as key -> value. The difference is that login does the identification on client side, doing the replacement of current user (if not identified already) or adding email if anonymous.

Update event just updates attributes for the current user.

Confirmation event

Purchases are the final goal of an online business. We limit confirmations by the orderId received in the event. So if a second event with the same orderId comes, it is discarded.

Email Open event

Email opens are limited at one each 20 minutes. The reason for this is that the huge variety of email clients usually generates so many email opens that are useless and not needed for the system.

All other events coming within 20 minutes after first one are discarded.

Was this article helpful?
Dislike 0
Views: 146