> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Event

> Create a new event to track conversions and user interactions

## Overview

This endpoint allows you to send event data to Cometly for tracking conversions, page views, and other user interactions. Events are processed asynchronously and will be queued for processing.

## Request Body

### Identification Requirements

**At least one of the following identification methods is required:**

1. **Email**: User's email address
2. **Comet Token**: Cometly tracking token
3. **Fingerprint + IP**: Both fingerprint and IP address must be provided together

<ParamField body="event_name" type="string" required>
  The name of the event being tracked. Use one of the standard events or a configured custom event.

  **Standard Events:**

  * `lead_generated`
  * `view_content`
  * `schedule`
  * `purchase`
  * `subscribe`
  * `add_to_cart`
  * `contact`
  * `initiate_checkout`
  * `add_payment_info`
  * `complete_registration`
  * `start_trial`
  * `sign_up`
  * `submit_application`
  * `webinar_registration`

  **Custom Events:**
  Custom events are named `custom_event_1` through `custom_event_50`. View our [help article](https://help.cometly.com/en/articles/8950752-creating-configuring-events) to learn how to configure custom events prior to sending to Cometly.
</ParamField>

### Tracking Parameters

<ParamField body="email" type="string">
  User's email address. Can be used as the primary identification method.
</ParamField>

<ParamField body="comet_token" type="string">
  Cometly tracking token. Can be used as the primary identification method.
</ParamField>

<ParamField body="fingerprint" type="string">
  Browser fingerprint for user identification. Must be provided together with `ip`.
</ParamField>

<ParamField body="ip" type="string">
  User's IP address. Must be provided together with `fingerprint`.
</ParamField>

<ParamField body="tracking_id" type="string">
  Custom tracking identifier. Events with the same tracking\_id will be attributed to the same contact.
</ParamField>

### User Information

<ParamField body="full_name" type="string">
  User's full name
</ParamField>

<ParamField body="first_name" type="string">
  User's first name
</ParamField>

<ParamField body="last_name" type="string">
  User's last name
</ParamField>

<ParamField body="phone" type="string">
  User's phone number
</ParamField>

### Session Information

<ParamField body="user_agent" type="string">
  Browser user agent string
</ParamField>

<ParamField body="event_time" type="string">
  Timestamp of when the event occurred. Accepts ISO 8601 format or Unix timestamp in seconds.
</ParamField>

<ParamField body="url" type="string">
  The URL where the event occurred
</ParamField>

### Ecommerce Data

<ParamField body="amount" type="number">
  Transaction amount (for purchase events)
</ParamField>

<ParamField body="order_id" type="string">
  Unique order identifier. **This field is used in our deduplication logic** — if multiple events are sent with the same `order_id`, they may be treated as duplicates. Ensure each distinct order uses a unique value.
</ParamField>

<ParamField body="order_name" type="string">
  Order name or description
</ParamField>

<ParamField body="checkout_token" type="string">
  Checkout session token
</ParamField>

<ParamField body="is_upsell" type="boolean">
  Indicates if this is an upsell transaction
</ParamField>

<ParamField body="upsell_common_id" type="string">
  Common identifier linking upsells to original orders
</ParamField>

### Attribution Parameters

<ParamField body="comet_source" type="string">
  Traffic source (e.g., "google", "facebook")
</ParamField>

<ParamField body="comet_network" type="string">
  Ad network name
</ParamField>

<ParamField body="comet_campaign" type="string">
  Campaign name or identifier
</ParamField>

<ParamField body="comet_ad_group" type="string">
  Ad group name or identifier
</ParamField>

<ParamField body="comet_ad_id" type="string">
  Specific ad identifier
</ParamField>

<ParamField body="comet_keyword" type="string">
  Keyword that triggered the ad
</ParamField>

<ParamField body="comet_type" type="string">
  Traffic type (e.g., "cpc", "organic")
</ParamField>

### Custom Fields

<ParamField body="profile_field_1 ... profile_field_30" type="string">
  Custom profile field values passed as root-level properties. Fields 1-15 accept text, 16-25 accept numbers, 26-30 accept dates.

  Example: `"profile_field_1": "Enterprise", "profile_field_16": "500"`
</ParamField>

### Advanced Options

<ParamField body="idempotency_key" type="string">
  Unique key to prevent duplicate event processing. Use this to safely retry requests.
</ParamField>

<ParamField body="do_not_capi" type="boolean">
  Set to `true` to prevent this event from being sent to Conversions API integrations
</ParamField>

## Response

### Success Response

<ResponseField name="status" type="number">
  HTTP status code (202)
</ResponseField>

<ResponseField name="message" type="string">
  Success message indicating the event was queued
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.cometly.com/public-api/v1/events/track \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "event_name": "purchase",
      "email": "customer@example.com",
      "amount": 99.99,
      "order_id": "ORD-12345",
      "url": "https://example.com/checkout/success",
      "event_time": "2024-01-15T10:30:00Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.cometly.com/public-api/v1/events/track', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      event_name: 'purchase',
      email: 'customer@example.com',
      amount: 99.99,
      order_id: 'ORD-12345',
      url: 'https://example.com/checkout/success',
      event_time: '2024-01-15T10:30:00Z'
    })
  });

  const data = await response.json();
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://app.cometly.com/public-api/v1/events/track';
  $headers = [
      'Authorization: Bearer YOUR_API_KEY',
      'Accept: application/json',
      'Content-Type: application/json'
  ];

  $data = [
      'event_name' => 'purchase',
      'email' => 'customer@example.com',
      'amount' => 99.99,
      'order_id' => 'ORD-12345',
      'url' => 'https://example.com/checkout/success',
      'event_time' => '2024-01-15T10:30:00Z'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);
  ?>
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime

  url = 'https://app.cometly.com/public-api/v1/events/track'
  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
  }

  data = {
      'event_name': 'purchase',
      'email': 'customer@example.com',
      'amount': 99.99,
      'order_id': 'ORD-12345',
      'url': 'https://example.com/checkout/success',
      'event_time': '2024-01-15T10:30:00Z'
  }

  response = requests.post(url, headers=headers, json=data)
  ```
</CodeGroup>

## Status Codes

| Status Code | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| 202         | Event accepted and queued for processing                                                  |
| 401         | Missing or invalid API key                                                                |
| 403         | API key doesn't have permission or subscription is inactive                               |
| 422         | Validation failed or missing required parameters                                          |
| 429         | Too many requests - rate limit exceeded. See [Rate Limiting](/introduction/rate-limiting) |

## Notes

* **Rate Limit**: This endpoint has a limit of **1000 requests per minute** per Space. See [Rate Limiting](/introduction/rate-limiting) for details.

## Validation Rules

* At least one identification method must be provided:
  * `email`, OR
  * `comet_token`, OR
  * Both `fingerprint` AND `ip` together
* `event_name` is required
* If `fingerprint` is provided, `ip` must also be provided (and vice versa)
* `event_time` accepts ISO 8601 format or Unix timestamp in seconds
* `amount` must be a number if provided

## Meta Deduplication

The **`idempotency_key`** in our API is a unique identifier that ensures data consistency and prevents duplication of events. You can extract the **`event_id`** from the Meta browser pixel and use it as the **`idempotency_key`** when interacting with our API. Upon an attributed Meta ad conversion event, we will send this value as `event_id` to prevent duplication, enabling Meta to recognize the `event_id` and deduplicate browser events.

<Note>
  Use the `idempotency_key` parameter to safely retry requests without creating duplicate events. The same idempotency key will prevent the event from being processed multiple times.
</Note>