Sending Past Events

If you have migrated from another service or just created a eSputnik account, and you have a history of

• user activity,
• subscriptions,
• or other events you want to use for advanced segmentation.

You can transfer the available event data from your CRM or other data store to the eSputnik system via the API resource Generate past events.

📘

Important

Before importing events, enable segmentation for the types of events you want to download. The type of a historical event isn't created automatically — if it doesn't exist or segmentation isn't enabled for it, the request returns the EVENT_SEGMENTATION_DISABLED error.

If your tariff plan does not include segmentation by events, please submit a request to [email protected].

By default, historical events are accepted with a depth of up to 366 days — for older events, the request returns the OCCURRED_TIME_TOO_DEPTH error. The limit can be extended for your account on request to support.

How to set up segmentation by events

To assign events to users, pre-import the contact list to your eSputnik account.

For example, you have a certain number of orders over the past year, and you want to build a segment with customers interested in a certain type of products or services, get statistics on the average order value, or segment contacts by geodata (if applicable).

Convert these subscriptions info into a JSON format supported for API according to the specification, and send them to the eSputnik system. You can send an array of up to 500 such events within one request. Specify the time of each event in the field occurred. Format of date: YYYY-MM-DD; format of date with the time: YYYY-MM-DDTHH:mm±hh:mm.

🚧

Important

• The date event parameter must be passed in the ISO 8601 format with a specified time zone offset relative to UTC. For example: 2025-01-05T13:00:00+02:00, where +02:00 indicates that the local time is 2 hours ahead of UTC.
• Note that some countries observe daylight saving time (DST), which may affect the offset.

📘

Note

Historical events uploaded via Generate past events are displayed in Event history but not in the Orders section. The Orders section shows only the order events passed through the standard mechanisms, such as the Add orders API method.

For example, you send an order of two mobile devices bought at a few years interval:

{
  "events": [
    {
      "eventTypeKey": "orderCreated",
      "keyValue": "test_v3_event_1",
      "params": {
        "phone": "380501234789",
        "externalOrderId": "12345679102",
        "externalCustomerId": "AA1100",
        "totalCost": "258.0",
        "status": "INITIALIZED",
        "date": "2025-01-05T13:00:00+02:00",
        "currency": "UAH",
        "items": [
          {
            "externalItemId": "200600",
            "name": "Super Device",
            "category": "devices",
            "quantity": 2,
            "cost": 999,
            "url": "http://example.com/item/200600",
            "imageUrl": "http://example.com/item/200600/image.png",
            "description": "High quality"
          }
        ]
      },
      "occurred": "2025-02-04T12:00"
    },
    {
      "eventTypeKey": "orderCreated",
      "keyValue": "test_v3_event_1",
      "params": {
        "phone": "380500000001",
        "externalOrderId": "12345679103",
        "externalCustomerId": "AA1111",
        "totalCost": "258.0",
        "status": "INITIALIZED",
        "date": "2025-01-07T13:00:00+02:00",
        "currency": "UAH",
        "items": [
          {
            "externalItemId": "200600",
            "name": "Super Device",
            "category": "devices",
            "quantity": 2,
            "cost": 999,
            "url": "http://example.com/item/200600",
            "imageUrl": "http://example.com/item/200600/image.png",
            "description": "High quality"
          }
        ]
      },
      "occurred": "2025-02-07T16:00"
    }
  ]
}

Apart from basic fields with the name, price, and link to a product, you can send any related data that is available to build segments. For example, you can send the country and city of the buyer to use for segmentation by geolocation.

{
  "city": "Los Angeles",
  "country": "USA"
}

Based on the available datasets you can build dynamic segment:

You can also delete old or irrelevant events. To do this, send a request to the same resource, but using the method type DELETE. Specify the time range to remove in the request body:

{
  "from": "2019-06-04",
  "to": "2020-01-04"
}

The method DELETE is inactive by default. To activate it, please contact our support team.

🚧

Important

• The method removes only historical events that were previously uploaded through Generate past events V3. It does not remove events sent through Generate event v3, which are cleared automatically once their storage period expires. It does not remove historical orders either — those are removed by a separate resource, Remove orders.
• Both bounds of the from/to range are inclusive. The endpoint accepts an exact time in UTC, not just a date.
• The published rate limit is 5 requests per second.
• If the feature is not enabled for your organisation, the endpoint returns 403 with a message stating that the organisation is not enabled for events removing.
• Processing is asynchronous and has no fixed SLA. The response confirms that the request was accepted, not that deletion has finished. Events are processed day by day, so the total duration depends on the amount of data.
• If some data has already aged out of the main storage under its TTL, this method does not remove it from segmented history.