Skip to main content
POST
/
public-api
/
v1
/
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:
  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 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.

​
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 CodeDescription
202Event accepted and queued for processing
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
422Validation failed or missing required parameters
429Too 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.