Synerise uses two APIs to send events, depending on the event type:
- the [`v4/events` API](https://developers.synerise.com/DataManagement/DataManagement.html#tag/Events) 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](https://developers.synerise.com/DataManagement/DataManagement.html#operation/CreateATransaction) and [batches](https://developers.synerise.com/DataManagement/DataManagement.html#operation/BatchAddOrUpdateTransactions)) is used to record `transaction.charge` events and automatically creates `product.buy` events for each transaction.
<!-- - the [/events/v1 API](https://developers.synerise.com/DataManagement/DataManagement.html#tag/AI-Events) is used to the following events: 
    - `recommendation.view`
    - `recommendation.click`
    - `item.search.click`  
    This API offers endpoints to send a single event or multiple events at once. In this article, we will focus on sending a single event. -->

## "Send Custom Event" endpoint


<div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content">

DO NOT send `transaction.charge` events as custom events.<br>
Transactions must be tracked with these endpoints:
- [`/v4/transactions`](https://developers.synerise.com/DataManagement/DataManagement.html#operation/CreateATransaction) (single transaction)
- [`/v4/transactions/batch`](https://developers.synerise.com/DataManagement/DataManagement.html#operation/BatchAddOrUpdateTransactions) (multiple transactions)

  </div></div></div>


  API reference available [here](https://developers.synerise.com/DataManagement/DataManagement.html#operation/CustomEvent).

  This endpoint can be used to send custom events required by your integration.  
  <!-- 
  <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content">

- Recommendation events must be sent to the [AI events API](#sending-recommendation-events).
- Transaction events must be sent to their dedicated endpoints. If you send a transaction event to the `/events/custom` or `/events/batch` endpoints, the `product.buy` sub-events aren't generated and transactions aren't handled correctly.

  </div></div></div>
  -->

  When you use this endpoint to send an event whose [definition](/docs/assets/events/event-definitions) 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](https://en.wikipedia.org/wiki/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.
    
   <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content">

   - 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`

   </div></div></div>

    

- `eventSalt` is a special parameter. Its usage is described in [Overwriting events](/developers/api/events/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`:


<pre><code class="language-json">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"
}'</code></pre>

### 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](#send-custom-event-endpoint)
- a `client.hitTimer` event (the dedicated endpoint is `/v4/events/hit-timer`), sent to a different profile


  <div class="highlight-code-block" data-hl-lines="8,9,22">
  <pre><code class="language-json">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"
      }
  ]'</code></pre>
  </div>


  <!-- ## Sending recommendation events

  These three types of events should be sent with a different API:
- `recommendation.view`
- `recommendation.click`
- `item.search.click`  

They can be sent as single events or as a batch.  

The AI events endpoints may use two authorization methods:
- A JWT, same as in other endpoints
- A tracker key sent as the `token` parameter of the query - this may be the same key included in the [tracking code](/developers/web/installation-and-configuration#creating-a-tracking-code) of your website or a separate one.
The API reference is available [here](https://developers.synerise.com/DataManagement/DataManagement.html#tag/AI-Events).

The request body must contain the following properties:
- `correlationId` is the ID of the recommendation frame where the event occurred. It is included in the `extras` object of a recommendation request.
- `clientUUID` is the UUID of the profile which made the request.
- `items` is an array of item IDs (as strings) that were included in the recommendation frame. It can be empty.

The following properties are optional:
- `eventTimestamp` is the Unix time of the occurrence, in milliseconds.
    - If no time is provided, the time when the event was received by Synerise is saved as the occurrence time.
    - If a future time is provided, the event is saved with an occurrence time in the future.
- `campaignId` is the ID of recommendation campaign.

#### Example: one event
The following cURL request is an example of sending a `recommendation.view` event. The viewed recommendation included one item.


<pre><code class="language-json">curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/events/v1/single/recommendation.view?token=56ba9d02-aaaa-aaaa-aaaa-018564059ea3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "correlationId": "5b0a0fcd-e76b-425c-b9e8-7d6d7bd4a79b",
    "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
    "items": [
        "89435879453"
    ],
    "eventTimestamp": "2022-12-08T13:23:22Z"
}'</code></pre>


#### Example: batch of events
All events in a batch must be of the same type. They can use different `clientUUID`s.

The following cURL request is an example of sending two `recommendation.view` events to the same profile (a customer saw two different recommendation frames, so the `correlationId` is different)


<pre><code class="language-json">curl --location --request POST 'https://api.synerise.com/events/v1/batch?token=56ba9d02-aaaa-aaaa-aaaa-018564059ea3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "eventType": "recommendation.view",
    "items": [
        {
            "correlationId": "5b0a0fcd-e76b-425c-b9e8-7d6d7bd4a79b",
            "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
            "items": [
                "89435879453"
            ],
            "eventTimestamp": "2022-12-08T13:49:00Z"
        },
        {
            "correlationId": "2232d7f8-611b-451b-a1f1-8134f73a04f0",
            "clientUUID": "e0097757-d1e2-44ac-ba3c-d97979a354c1",
            "items": [
                "475677345"
            ],
            "eventTimestamp": "2022-12-08T13:51:00Z"
        }
    ]
}'</code></pre>

 -->