Introduction | ThoughtMetric Docs

Data insert API

This is the API our tracking pixel uses to send pageview, order and customer events into ThoughtMetric. You can call it directly instead of, or alongside, the pixel — from your own server, or from a tool like Rudderstack.

This is an advanced integration. Most stores should install the tracking pixel and an e-commerce integration instead, which handle all of this for you. Reach for this API for fully custom implementations, or to feed in data the pixel cannot see, such as offline or phone orders.

Endpoint

Every event goes to the same endpoint. All fields are passed as query parameters, and which ones you send depends on the event. Both GET and POST are accepted, and behave identically.

Endpoint

GET https://data.thoughtmetric.io/d

Identifying your store

The id parameter is your Project ID and associates the data with your account. Find it in the dashboard under Configure → API. It looks like this:

Project ID

ID-bcd0aa692ce7e6b2

There is no API key on this endpoint. The Project ID is an identifier, not a secret, and the endpoint accepts anything sent to it. Do not rely on it to keep data out; do validate on your side that you are only sending events you intend to record.

What comes back

The endpoint responds with the tracking pixel asset and a 200, because browsers load it as a script. It returns the same thing whether or not your event was usable, so the response does not tell you if the data was accepted. Events are queued and processed asynchronously, and malformed ones are dropped during processing.

After sending events, confirm they arrived by querying the REST API or checking your dashboard. Data appears once the processing pipeline has run, not instantly.

Common parameters

These apply to every event. The individual event pages list what each one needs.

id string, required	Your Project ID, e.g. `ID-bcd0aa692ce7e6b2`.
uid string, required	A UUID that uniquely identifies this visitor, stored in a cookie by the pixel. Reuse the same value across a visitor's events so they tie together into one session and one customer.
ht string, required	Hit type: `pageview`, `event`, `identify` or `survey`. See the table below.
ev string	Event name. Required when `ht` is `event`: `order`, `addToCart`, `viewContent` or `lead`.
ed string	JSON object holding the payload, used by order, identify and lead events. See the relevant event page for its fields.
cid string	Customer ID, usually an email address. Required when `ht` is `identify`.
v string	Version of the client sending the data. Send `api` when calling this endpoint directly.
ts string	Time the event happened. ISO 8601 or a Unix timestamp in seconds. Defaults to no timestamp if it cannot be parsed, so send it explicitly.
dl string	URL of the page the event happened on. Used for landing page and UTM attribution, so include query parameters.
rl string	Referring page URL. Used to attribute the visit to a channel.
dt string	Page title.
ua string	Visitor's user agent string. Send this when calling server-side, since we cannot read it from your server's request.
ip string	Visitor's IP address, used for geolocation and matching. Omit it entirely and we use the IP the request came from, which server-side is your server, not your customer. Send it as an empty value to record no IP at all.
dc string	Discount code associated with the event.
fp string	Browser fingerprint. Combined with the IP for cross-device matching.
fbp string	Facebook _fbp cookie value, if you have one.
fbc string	Facebook _fbc cookie value, if you have one.

Hit types and events

ht decides how the hit is processed. When it is event, the ev parameter says which event it is. Anything else is ignored.

ht=pageview pageview	A page view. The basis of sessions and attribution.
ht=identify customer	Customer details. Requires cid, and is dropped without it.
ht=event&ev=order order	A completed order. Requires a transaction_id in ed, and is dropped without it.
ht=event&ev=addToCart event	An add-to-cart. Counts toward the add_to_carts metric.
ht=event&ev=viewContent event	A product view. Counts toward the view_contents metric.
ht=event&ev=lead event	A lead. Counts toward the leads metric.

Sending a complete picture

Reuse one uid per visitor. It is what ties pageviews, orders and customer records together, and what lets us attribute an order back to the visit that produced it.
Always pair an order with a customer event. Without it we cannot tell whether the buyer is new or returning.
Orders are de-duplicated on transaction_id and customers on cid. Re-sending either updates the existing record, which is how you push status changes, refunds and price corrections.

Events

Pageview ht=pageview Record a page view. Order ht=event&ev=order Record or update an order. Customer ht=identify Record or update a customer. Add to cart ht=event&ev=addToCart Record an add-to-cart. View product ht=event&ev=viewContent Record a product view.