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

**event\_name** `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.

### Tracking Parameters

**email** `string`

User's email address. Can be used as the primary identification method.

**comet\_token** `string`

Cometly tracking token. Can be used as the primary identification method.

**fingerprint** `string`

Browser fingerprint for user identification. Must be provided together with `ip`.

**ip** `string`

User's IP address. Must be provided together with `fingerprint`.

**tracking\_id** `string`

Custom tracking identifier. Events with the same tracking\_id will be attributed to the same contact.

**company\_external\_id** `string`

Groups this contact into a company using your own account or company identifier. Nullable; accepts a string or integer, trimmed, 1–190 characters after trimming. The value is case-preserved and stored byte-exact — it is never lowercased. A blank string is treated as absent (`null`). Sending a float, array, or boolean returns a `422`.

This is unrelated to `tracking_id`: `tracking_id` merges events into a single contact and never groups companies, while `company_external_id` groups contacts into a company and never merges contacts or takes part in contact matching. Never send a shared account ID as `tracking_id`.

Only honored when the Space's company identity mode is set to **External ID** in Space Settings. In the default **Auto** mode (companies grouped by business-email domain), the value is still accepted and stored, but ignored for grouping.

**company\_name** `string`

Display name for the company identified by `company_external_id`. Nullable; accepts a string or integer, trimmed, 1–255 characters after trimming. A blank string is treated as absent (`null`). Sending a float, array, or boolean returns a `422`.

Last write wins, and the value is never used for matching — two companies with the same name stay separate. Ignored when `company_external_id` is not also provided, since `company_name` alone doesn't identify a company to name.

### User Information

**full\_name** `string`

User's full name

**first\_name** `string`

User's first name

**last\_name** `string`

User's last name

**phone** `string`

User's phone number

### Session Information

**user\_agent** `string`

Browser user agent string

**event\_time** `string`

Timestamp of when the event occurred. Accepts ISO 8601 format or Unix timestamp in seconds.

**url** `string`

The URL where the event occurred

### Ecommerce Data

**amount** `number`

Transaction amount (for purchase events)

**order\_id** `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.

**order\_name** `string`

Order name or description

**checkout\_token** `string`

Checkout session token

**is\_upsell** `boolean`

Indicates if this is an upsell transaction

**upsell\_common\_id** `string`

Common identifier linking upsells to original orders

### Custom Fields

**profile\_field\_1 ... profile\_field\_30** `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"`

### Advanced Options

**idempotency\_key** `string`

Unique key to prevent duplicate event processing. Use this to safely retry requests.

**do\_not\_capi** `boolean`

Set to `true` to prevent this event from being sent to Conversions API integrations

## Response

### Success Response

**status** `number`

HTTP status code (202)

**message** `string`

Success message indicating the event was queued

### Error Response

**message** `string`

Error description explaining what went wrong

## Example Requests

```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",
    "company_external_id": "acct_8f3k2",
    "company_name": "Acme Inc"
  }'
```

```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',
    company_external_id: 'acct_8f3k2',
    company_name: 'Acme Inc'
  })
});

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',
    'company_external_id' => 'acct_8f3k2',
    'company_name' => 'Acme Inc'
];

$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',
    'company_external_id': 'acct_8f3k2',
    'company_name': 'Acme Inc'
}

response = requests.post(url, headers=headers, json=data)
```

## 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](https://docs.cometly.com/introduction/rate-limiting.md) |

## Notes

* **Rate Limit**: This endpoint has a limit of **1000 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) 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
* `company_external_id`, if provided, must be a string or integer, 1–190 characters after trimming; floats, arrays, and booleans return `422`
* `company_name`, if provided, must be a string or integer, 1–255 characters after trimming; floats, arrays, and booleans return `422`
* Blank strings for `company_external_id` or `company_name` are treated as absent (`null`); `company_name` is ignored when `company_external_id` isn't also 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.