Track Event

Track a custom event for a subscriber. This is used to trigger workflows that listen for the specified event name.

POST

 https://s2s.pushengage.com/api/v1/events

Headers

Header	Value	Required
Api-Key	Your API key	Yes
Content-Type	application/json	Yes

Request Body

Property Name	Type	Required	Description
event_name	String	Yes	Name of the custom event. Max 64 characters. Must not start with "PushEngage.".
device_token_hash	String	Conditional	Subscriber's device token hash. Required if profile_id is not provided.
profile_id	String	Conditional	Subscriber's profile ID. Required if device_token_hash is not provided. If both are provided, profile_id takes priority.
data	Object	No	Key-value pairs sent with the event. Keys must start with a letter or digit and can contain letters, digits, hyphens, and underscores (max 255 chars). Values must be string, number, boolean, or ISO 8601 date. Max payload size: 4KB.

Example

Request

cURL

curl -X POST https://s2s.pushengage.com/api/v1/events \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "add_to_cart",
    "device_token_hash": "DEVICE_TOKEN_HASH",
    "profile_id": "PROFILE_ID",
    "data": {
      "product_name": "Running Shoes",
      "price": 99.99
    }
  }'

PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://s2s.pushengage.com/api/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event_name' => 'add_to_cart',
    'device_token_hash' => 'DEVICE_TOKEN_HASH',
    'profile_id' => 'PROFILE_ID',
    'data' => [
      'product_name' => 'Running Shoes',
      'price' => 99.99
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Api-Key: YOUR_API_KEY",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>

JavaScript

const response = await fetch('https://s2s.pushengage.com/api/v1/events', {
  method: 'POST',
  headers: {
    'Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_name: 'add_to_cart',
    device_token_hash: 'DEVICE_TOKEN_HASH',
    profile_id: 'PROFILE_ID',
    data: {
      product_name: 'Running Shoes',
      price: 99.99,
    },
  }),
});

const result = await response.json();
console.log(result);

Response

200 OK

{
  "error_code": 0,
  "data": {}
}

401 Unauthorized

{
  "error": {
    "message": "API key is required. Please provide a valid API key in the API-KEY header.",
    "code": 401002
  }
}

{
  "error": {
    "message": "Invalid API key. The provided API key was not found or is incorrect.",
    "code": 401000
  }
}

400 Bad Request

{
  "error": {
    "message": "Invalid data",
    "code": 1003,
    "details": [
      {
        "message": "event_name is required",
        "path": ["event_name"]
      }
    ]
  }
}

500 Internal Server Error

{
  "error": {
    "message": "Something went wrong.",
    "code": 1001
  }
}

Notes

• You must provide either device_token_hash or profile_id. If both are provided, profile_id takes priority.
• The data payload is limited to 4KB.
• Event data values must be string, number, boolean, or ISO 8601 date.
• For client-side event tracking (from the browser), use the Web SDK's PushEngage.trackEvent() method instead.