Create Event - Cometly API Docs

Create Event

curl --request POST \
  --url https://app.cometly.com/public-api/v1/events/track \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_name": "<string>",
  "email": "<string>",
  "comet_token": "<string>",
  "fingerprint": "<string>",
  "ip": "<string>",
  "tracking_id": "<string>",
  "full_name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone": "<string>",
  "user_agent": "<string>",
  "event_time": "<string>",
  "url": "<string>",
  "amount": 123,
  "order_id": "<string>",
  "order_name": "<string>",
  "checkout_token": "<string>",
  "is_upsell": true,
  "upsell_common_id": "<string>",
  "comet_source": "<string>",
  "comet_network": "<string>",
  "comet_campaign": "<string>",
  "comet_ad_group": "<string>",
  "comet_ad_id": "<string>",
  "comet_keyword": "<string>",
  "comet_type": "<string>",
  "profile_field_1 ... profile_field_30": "<string>",
  "idempotency_key": "<string>",
  "do_not_capi": true
}
'

{
  "status": 123,
  "message": "<string>"
}

POST

public-api

events

track

Create Event

curl --request POST \
  --url https://app.cometly.com/public-api/v1/events/track \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_name": "<string>",
  "email": "<string>",
  "comet_token": "<string>",
  "fingerprint": "<string>",
  "ip": "<string>",
  "tracking_id": "<string>",
  "full_name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone": "<string>",
  "user_agent": "<string>",
  "event_time": "<string>",
  "url": "<string>",
  "amount": 123,
  "order_id": "<string>",
  "order_name": "<string>",
  "checkout_token": "<string>",
  "is_upsell": true,
  "upsell_common_id": "<string>",
  "comet_source": "<string>",
  "comet_network": "<string>",
  "comet_campaign": "<string>",
  "comet_ad_group": "<string>",
  "comet_ad_id": "<string>",
  "comet_keyword": "<string>",
  "comet_type": "<string>",
  "profile_field_1 ... profile_field_30": "<string>",
  "idempotency_key": "<string>",
  "do_not_capi": true
}
'

{
  "status": 123,
  "message": "<string>"
}

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:

Email: User’s email address
Comet Token: Cometly tracking token
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 to learn how to configure custom events prior to sending to Cometly.

Tracking Parameters

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.

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.

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

Attribution Parameters

comet_source

string

Traffic source (e.g., “google”, “facebook”)

comet_network

string

Ad network name

comet_campaign

string

Campaign name or identifier

comet_ad_group

string

Ad group name or identifier

comet_ad_id

string

Specific ad identifier

comet_keyword

string

Keyword that triggered the ad

comet_type

string

Traffic type (e.g., “cpc”, “organic”)

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

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"
  }'

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

Notes

Rate Limit: This endpoint has a limit of 1000 requests per minute per Space. See 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.

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.

Changelog List Events

⌘I

​Overview

​Request Body

​Identification Requirements

​Tracking Parameters

​User Information

​Session Information

​Ecommerce Data

​Attribution Parameters

​Custom Fields

​Advanced Options

​Response

​Success Response

​Error Response

​Example Requests

​Status Codes

​Notes

​Validation Rules

​Meta Deduplication

Overview

Request Body

Identification Requirements

Tracking Parameters

User Information

Session Information

Ecommerce Data

Attribution Parameters

Custom Fields

Advanced Options

Response

Success Response

Error Response

Example Requests

Status Codes

Notes

Validation Rules

Meta Deduplication