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 Comet Events spaces (workspaces). Please ensure your space is a Comet Events space prior to setup.

For the highest attribution accuracy, we require a IP and fingerprint. The fingerprint should be obtained from the available cometFingerprint() function available via the Cometly Pixel base code present on all pages of the site.

Important Testing Information:
The Cometly script activates the first time the visitor comes to your site and has a specific UTM configuration on the URL. When the visitor comes back again to your site organically without UTM's on your URL, the Cometly script will automatically identify the visitor is returning.

For testing the Cometly script and obtaining the fingerprint from the cometFingerprint() function, please append the following UTM parameters to your URL to activate the Cometly script for testing:

?utm_campaign=123456789&utm_source=facebook

Your URL should look like like this: https://example.com/?utm_campaign=123456789&utm_source=facebook

You can then easily identify the fingerprint inside the cometFingerprint() function.
‍

For any questions, please contact developers@cometly.com

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 Tracking Page inside your Cometly account to retrieve the script.
‍

After you are on the Tracking Setup page, click Setup Comet 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 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

Endpoints

As of right now, 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.

For purchase
‍

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, and fingerprint or uid for the best attribution accuracy.

However, depending on your data source, you may not be able to retrieve a required fingerprint or uid below.

In this scenario, you can send the email field without a fingerprint or uid 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:
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
fingerprint string
*required if uid or email is not present

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.

Important Testing Information & Obtaining Fingerprint:
The Cometly script activates the first time the visitor comes to your site and has a specific UTM configuration on the URL. When the visitor comes back again to your site organically without UTM's on your URL, the Cometly script will automatically identify the visitor is returning.

For testing the Cometly script and obtaining the fingerprint from the cometFingerprint() function, please append the following UTM parameters to your URL to activate the Cometly script for testing:

?utm_campaign=123456789&utm_source=facebook

Your URL should look like like this:
‍https://example.com/?utm_campaign=123456789&utm_source=facebook

You can then easily identify the fingerprint inside the cometFingerprint() function.
uid string
*required if fingerprint or email is not present

If a fingerprint cannot be used, a unique identifier for this user should be passed to the public api. If this identifier is not unique, cross tracking will likely happen.
email string
*required
ip string
*required

Optional fields

Customer & Hit 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
UTM Data:
utm_source string
utm_medium string
utm_campaign string
utm_term string
utm_content string
Ecommerce Data:
order_id string
order_name string
checkout_token string
amount number
Event Data:
event_time timestamp, should be UTC timezone

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

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


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

import "fmt"

func main() {
  fmt.Println("Hello, 世界")
}


# 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


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

{
    "event_name" : "lead",
    "email" : "developers@cometly.com",
    "fingerprint" : "abcdef1234567890",
    "first_name" : "John",
    "last_name" : "Smith",
    "ip" : "123.123.123.123",
    "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",
    "utm_source" : "facebook",
    "utm_campaign" : "132435465768",
    "event_time" : 1677093110
}

{
    "event_name" : "purchase",
    "email" : "developers@cometly.com",
    "fingerprint" : "abcdef1234567890",
    "ip" : "123.123.123.123",
    "first_name" : "John",
    "last_name" : "Smith",
    "amount" : 55.44,
    "event_time" : 1677093110
}

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

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

GTM

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.

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

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

New Section

New Child Method

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

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.

curl https://api.stripe.com/v1/credit_notes/cn_1FWqvi2eZvKYlo2CZd3TwT6n \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "metadata[order_id]=6735"

var stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

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

GTM

New Section

Introduction

Script Installation

API Token

Authentication

Endpoints

Required fields

event_name string

fingerprint string

uid string

email string

ip string

Optional fields

full_name string

first_name string

last_name string

user_agent string

phone string

utm_source string

utm_medium string

utm_campaign string

utm_term string

utm_content string

order_id string

order_name string

checkout_token string

amount number

event_time timestamp, should be UTC timezone

Request ID's

Authentication

post responses

GET responses

error handling

GTM

Fingerprint Data Layer

Authentication

post responses

GET responses

error handling

Something Else

Attributes

type string

doc_url required

charge string

code string

New Section

New Child Method

Authentication

post responses

GET responses

error handling

Something Else

Attributes

type string

doc_url required

charge string

code string