Sending events

Synerise uses two APIs to send events, depending on the event type:

• the v4/events API is used to send most events, including custom ones.
  This API offers multiple endpoints specific to a particular event type. In this article, we will take a closer look at using the “Send Custom Event” endpoint and at the “Batch send events” endpoint.
• the v4/transactions API (for single transactions and batches) is used to record transaction.charge events and automatically creates product.buy events for each transaction.

“Send Custom Event” endpoint

API reference available here.

This endpoint can be used to send custom events required by your integration.

When you use this endpoint to send an event whose definition doesn’t exist in the system, a definition is created automatically.

The request body must contain the following properties:

• action is the type of event, for example page.visit (default event), dog.bark (custom event).
  When you use a dedicated endpoint for an event type, this parameter is not used.
• client is an object with profile identifiers. It must contain at least one of the following identifiers:
  • id
  • customId
  • uuid
  • email
• label must be a non-empty string. It is a legacy property, currently not used by Synerise and not saved in persistent storage.

The following properties are optional:

• params is an object with additional event parameters that you want to add to the request. Some names are reserved for system use (see API reference for details).

• time is the time when the event occurred (for example, the time when a customer clicked a button), formatted according to ISO 8601. Example:
  If your timezone is UTC-4 and your local time is 09:00:00, May 23, 2022:

  • You can send the time as UTC: 2022-05-23T13:00:00Z
  • You can send the same time with your timezone: 2022-05-23T09:00:00-04:00
  • You can send the same time with a different timezone, if necessary: 2022-05-23T07:00:00-06:00

  All the above examples indicate the same date and time, written in different ways.
  You can include milliseconds, for example 2022-05-23T13:00:00.176Z
  The time sent in this parameter is not affected by the time zone of your workspace. You can use any timezone or the UTC standard.
  When you retrieve an event later, the time is always returned as UTC.

  Important:

  • If no time is provided, the time when the event was received by Synerise is saved as the occurrence time.
  • If the provided time is in the future, it is rejected and the time when the event was received by Synerise is saved as the occurrence time. In the above example, future times would be:
    • later than 2022-05-23T13:00:00Z
    • later than 2022-05-23T09:00:00-04:00
    • later than 2022-05-23T07:00:00-06:00

• eventSalt is a special parameter. Its usage is described in Overwriting events.

The request can be authorized with a JWT of a profile (formerly called a client) or a workspace (formerly called a business profile).

Example

The following cURL request is an example of a custom dog.bark event with a few custom properties: loudness, mood, and mailmanScared:

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer ey...RtH_g' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "dog.bark",
    "client": {
        "id": 5092159999
    },
    "time": "2022-11-28T12:18:27Z",
    "params": {
        "loudness": 3,
        "mood": "happy",
        "mailmanScared": true
    },
    "label": "bark"
}'

Sending a batch of events

You can also send a number of events at once. A batch can include different event types saved to different profiles.

The request body is an array of events similar to when sending a single events, with the following modification:

• if the event is custom, add the "type": "custom" parameter
• if the event has a dedicated endpoint:
  • add the type parameter with the value that corresponds to the name of the dedicated endpoint. For example, if the endpoint of the event is /v4/events/shared, the type is shared.
  • remove the action parameter.

Example

The following cURL request is a batch of two events:

• the same dog.bark event from the previous example
• a client.hitTimer event (the dedicated endpoint is /v4/events/hit-timer), sent to a different profile

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer ey...RtH_g' \
--data-raw '[
    {
        "action": "dog.bark",
        "type": "custom",
        "client": {
            "id": 5092159999
        },
        "time": "2022-11-28T12:18:27Z",
        "params": {
            "loudness": 3,
            "mood": "happy",
            "mailmanScared": true
        },
        "label": "bark"
    },
    {
        "type": "hit-timer",
        "time": "2022-11-26T13:13:48Z",
        "client": {
            "id": 267498412
        },
        "label": "string"
    }
]'