---
title: Send Event
description: "### The Event API The event API allows you to insert bulk event data to *Releva*. Any insert submitted through this API will be live within 10 seconds of receiving a successful response. ### Do I need to call it?…"
url: "https://releva.ai/documentation/events/custom-event-api/"
updated: "2026-09-22"
category: Developer Documentation / Events
---

# Send Event

### The Event API

The event API allows you to insert bulk event data to *Releva*. Any insert submitted through this API will be live within 10 seconds of receiving a successful response.

### Do I need to call it?

Yes, if you want to update user profile data with custom events from your back end.

### Request Parameters

You may perform requests to the API using the following curl equivalent:

```js
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <secretKey>' -XPOST https://releva.ai/api/v0/events -d'{
    "events": [
        {
            "locale": "bg",
            "action": "search",
            "products": [
                {"id": "123"},
                {"id": "456"},
                {"id": "789"}
            ],
            "custom": {
                "string": [
                    {
                        "key": "agent",
                        "values": [
                            "manual"
                        ]
                    },
                    {
                        "key": "name",
                        "values": [
                            "I. Z."
                        ]
                    },
                    {
                        "key": "imageURL",
                        "values": [
                            "https://....."
                        ]
                    },
.....
                ]
            },
            "email": "georgi@releva.ai"
        },
        {
            "locale": "bg",
            "action": "clicked",
            "products": [
                {
                  "id": "123",
                  "custom": {
                    "string": [
                      {"key": "color", "values": ["black"]}
                    ]
                  }
                },
                {"id": "456"},
                {"id": "789"}
            ],
            "phoneNumber": "+359123"
....
        }
    ]
}'
```

### The events Array

This object is an array of Objects with the following properties.

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| **profileId** | String | The unique id of the user this event refers to. This Id needs to be consistent with the profile.id you send us in the frontend integration (See [Standard integration 1](https://releva.ai/documentation/developer-documentation/front-end-integration/)) |
| **email** | String (Optional) | The phoneNumber of the user this event refers to. Either this or "phoneNumber" needs to be set. |
| **phoneNumber** | String (Optional) | The phoneNumber of the user this event refers to. Either this or "email" needs to be set. |
| **action** | String | This is the name of the action this event refers to. |
| **locale** | [ISO-639-1 String](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | If you support multiple languages or currencies, set this to the current locale. |
| **products\[\].id** | String (Optional) | Products identifiers associated with this event. |
| **products\[\].custom** | Object (Optional) | Product custom fields |
| **timestamp** | [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) String (Optional) | The date and time when this event happened. |
| **custom** | Object (Optional) | The custom fields associated with the event. |
| **orderId** | String (Optional) | A unique order ID that identifies the completed order once a cart has been checked out. If the cart is not checked out, this should not be set. |
| **companyId** | Object (Optional) | The company id of the company this event should be associated with. |

### Response Format

A successful response will return HTTP Status `202` with an empty response body (`{}`).

An error response will return a HTTP `4xx` or `5xx` status code and have the following structure:

```json
{
  "message": "A description of the error and how to fix it, if it's a client error."
}
```