Introduction

Use the Cometly API to send events from all your data sources to Cometly.

The Cometly API will receive data from your data sources so Cometly can match events back to the correct site visitor profile and ad. It's a requirement that the Comet script is installed on each page of your site just above the </head> tag for Cometly to accurately attribute events.

The Cometly API will only work for Events spaces (workspaces). Please ensure your space is a Events space prior to setup.

For the highest attribution accuracy, we recommend sending a IP and fingerprint and comet_token.

The fingerprint should be obtained from the available cometFingerprint() function available via the Cometly Pixel base code present on all pages of the site.

The comet_token should be obtained from the available cometToken() function available via the Cometly Pixel base code present on all pages of the site.

The Cometly Pixel is a small piece of code that gives you a clearer insight into your website visitors. It tracks the pages they visit and automatically updates their profile when they submit forms. Be sure to place the pixel on every page of your website, right before the </head> tag ends.

And remember, it’s crucial to include it on every step of your customer's journey, whether that's within your sales funnels or across multiple domains. What’s more, the Cometly Pixel is intuitive—it doesn't just recognize users across different devices, it also knows when the same person returns to your site. This means you'll always know when someone comes back, giving you a full view of each visitor's interaction with your site over time.

Automatic Form Data Capture:
The Cometly base pixel will automatically updates the visitors profile when a form is filled out. You will automatically see the first name, last name, (or full name), email, and phone number inside Cometly if the visitor came from an ad. Each space in Cometly has a unique Cometly Pixel. You need to ensure you have the correct Cometly pixel if you are using multiple spaces in your account.

For any questions, please contact developers@cometly.com

Learn More The Cometly Pixel →

Script Installation

Each space (workspace) inside Cometly has a unique script. It's a requirement that the script is installed on each page of your site just above the </head> tag for Cometly to accurately attribute events

Obtaining Your Script
Cometly accounts can have multiple spaces (workspaces) and each space has a unique script. Ensure you are installing the correct script on your site if you have multiple spaces.

Visit the Events Manager inside your Cometly account to retrieve the script.


On the Events Manager page, click Setup Events and copy the pixel. Install the script just above the </head> tag on every page of your site.

Since you're using the API to send events, you do not need to proceed to 'Step 2: Add your events'.

API Token

Each space (workspace) inside Cometly has a unique API token.

Obtaining Your API Token
Cometly accounts can have multiple spaces (workspaces) and each space has an API token. Cometly API can only work for Comet Events spaces.

Visit the Space Settings Integrations page for the Cometly space that you want to receive data, click Cometly API, and generate a new API token.

For security reasons, the API token will only be shown once, make sure to copy this token to a safe place. If you lose the token, you can always regenerate a new token in the future.

Authentication

Authorization

Put the access token in the Authorization: Bearer <TOKEN> header.

Example: Authorization: Bearer 123


Required Headers

Accept: application/json

Content-Type: application/json

Important

The standard API is not suitable for use in client-side scripts (e.g. jQuery, Javascript). Using it on the client-side would require exposing sensitive API credentials; giving anyone access to your account.

Endpoints

We only have one endpoint which allows the posting of an event to our tracking engine.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Important:
If your event is associated with personal identifiable information, please include the email, name, and phone strings to fully use the Customer Journey feature. Please include as many attributes as possible below to improve accuracy.

Note: It's highly recommended that you include an IP, email, comet_token and fingerprint for the best attribution accuracy.

If you cannot retrieve the fingerprint + IP or comet_token, you must send the email field and Cometly will attribute by email only. This could limit attribution accuracy depending on your marketing funnel. When only sending the email field, your marketing funnel must have a form in the beginning pages of the marketing funnel with an email field that our script will automatically capture.

For any questions, please contact developers@cometly.com

Required fields
  • event_name string

    One of the following events is required:

    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:

    View our help article to learn how to configure custom events prior to sending to Cometly.

    custom_event_1

    custom_event_2

    custom_event_3

    custom_event_4

    custom_event_5

    custom_event_6

    custom_event_7

    custom_event_8

    custom_event_9

    custom_event_10

    custom_event_11

    custom_event_12

    custom_event_13

    custom_event_14

    custom_event_15

    custom_event_16

    custom_event_17

    custom_event_18

    custom_event_19

    custom_event_20

    custom_event_21

    custom_event_22

    custom_event_23

    custom_event_24

    custom_event_25

  • email string

    *required if both fingerprint and IP are missing

  • fingerprint string


    *required if email is missing

    The fingerprint should be obtained from the available cometFingerprint() function available via the Cometly tracking code. The function returns a promise that resolves to the fingerprint value.

  • comet_token string


    *required if email or fingerprint + IP are missing

    The comet_token should be obtained from the cometToken() function available via the Cometly tracking code. The function returns a string.

  • ip string

    *required if email is missing

ALL fields
  • Customer & Event Data:

    full_name string

    first_name string

    last_name string

    user_agent string

    phone string

    Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching (e.g., the number 1 must precede a phone number in the United States). Always include the country code as part of your customers' phone numbers, even if all of your data is from the same country.

    Example
    Input: US phone number (650)555-1212
    Normalized format: 16505551212

  • Event Data:

    event_time timestamp, should be UTC timezone

    *recommended

  • Ecommerce Data:

    order_id string

    order_name string

    checkout_token string

    amount number

  • Meta Deduplication:

    idempotency_key string


    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.

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);
POST
/v1/ava/endpoint/ids

// You can edit this code!
// Click here and start typing.
package main

import "fmt"

func main() {
  fmt.Println("Hello, 世界")
}
POST
/v1/ava/endpoint/ids

# Python 3: Fibonacci series up to n
>>> def fib(n):
>>>     a, b = 0, 1
>>>     while a < n:
>>>         print(a, end=' ')
>>>         a, b = b, a+b
>>>     print()
>>> fib(1000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
POST
URL

https://app.cometly.com/public-api/v1/events

EXAMPLE PAYLOAD
{
    "event_name" : "lead_generated",
    "email" : "developers@cometly.com",
    "comet_token" : "ddffd8d8338383883838484843838388d8df8f",
    "fingerprint" : "abcdef1234567890",
    "first_name" : "John",
    "last_name" : "Smith",
    "ip" : "123.123.123.123",
    "amount" : 34,
    "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15",
    "event_time" : 1677093110
}



Important:
When only sending the event_name and email, your marketing funnel must have a form in the beginning pages of the marketing funnel with an email field that our Cometly code script will automatically capture.

MINIMUM REQUIREMENT PAYLOAD FOR EVENTS
{
    "event_name" : "lead_generated",
    "email" : "developers@cometly.com",
}

Use the Events Log to Verify Incoming POST Requests

Cometly features an in-built events log system designed to help you monitor and validate the data you send through POST requests. This tool is invaluable for troubleshooting, ensuring that the data you're transmitting to our services is received correctly and in its entirety. Below, we've outlined the steps on how to utilize the events log for this purpose.

Accessing the Events Log

Visit the Events Log page in the app to access the logs section. Please allow up to 15 minutes for the events to process and display in the Events Log. If you are not seeing any events, please contact support@cometly.com and we will assist.

Request ID's

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

Authentication

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

post responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

GET responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

error handling

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

Fingerprint Data Layer

Create a Custom HTML tag inside GTM with the script to the right.



using fingerprint

You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Was this section helpful?

Authentication

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

post responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

GET responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

error handling

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

Something Else

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" instead of -u sk_test_4eC39HqLyjWDarjtT1zdp7dc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Attributes
  • type string

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique.

  • doc_url required

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique.

  • charge string

    For card errors, the ID of the failed charge.

  • code string

    For some errors that could be handled programmatically, a short string indicating the error code reported.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

New Child Method

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

Authentication

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

post responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

GET responses

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

error handling

Test mode secret keys have the prefix Alternatively, you can use for granular permissions.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);

Something Else

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" instead of -u sk_test_4eC39HqLyjWDarjtT1zdp7dc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Attributes
  • type string

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique.

  • doc_url required

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique.

  • charge string

    For card errors, the ID of the failed charge.

  • code string

    For some errors that could be handled programmatically, a short string indicating the error code reported.

Was this section helpful?

POST
/v1/ava/endpoint/ids
curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"
POST
/v1/ava/endpoint/ids
var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.creditNotes.retrieve(
  'cn_1FWuAc2eZvKYlo2C1Kbk7sKK',
  function(err, creditNote) {
    // asynchronously called
  }
);