Data insert API

Customer

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

Records a customer. Customers are de-duplicated on cid, so re-sending one updates the existing record. Send this alongside every order.

created_at is what makes a customer new or returning. It must be the date of the customer's first ever order, not the current one. For a genuinely first-time buyer, send the order's own timestamp. Get this wrong and new-versus-returning reporting, customer LTV and cost-per-new-customer will all be wrong.

Example request

curl -G https://data.thoughtmetric.io/d \
  -d id=ID-bcd0aa692ce7e6b2 \
  -d uid=8824a9fc-002d-4fb8-bcea-9e60225a88f0 \
  -d ht=identify \
  -d cid=customer@example.com \
  -d v=api \
  -d ip=203.0.113.42 \
  -d ts=2024-01-31T18:22:04Z \
  --data-urlencode 'ed={"email":"customer@example.com","created_at":"2022-09-06 20:12:44 -0400","total_spent":455.00,"orders_count":3,"first_name":"Ada","last_name":"Lovelace"}'

<?php

$baseUrl = "https://data.thoughtmetric.io/d";

$params = [
    "id"  => "ID-bcd0aa692ce7e6b2",
    "uid" => "8824a9fc-002d-4fb8-bcea-9e60225a88f0", // same uuid as the order and pageviews
    "ht"  => "identify",
    "cid" => "customer@example.com",
    "ed"  => json_encode([
        "email"        => "customer@example.com",
        "created_at"   => "2022-09-06 20:12:44 -0400", // date of their FIRST ever order
        "total_spent"  => 455.00,
        "orders_count" => 3,
        "first_name"   => "Ada",
        "last_name"    => "Lovelace",
    ]),
    "v"   => "api",
    "ip"  => "203.0.113.42",
    "dl"  => "https://example-store.com/checkout/thank-you",
    "ts"  => time(),
];

$url = $baseUrl . "?" . http_build_query($params);
file_get_contents($url);

const customer = {
  email: "customer@example.com",
  created_at: "2022-09-06 20:12:44 -0400", // date of their FIRST ever order
  total_spent: 455.00,
  orders_count: 3,
  first_name: "Ada",
  last_name: "Lovelace",
};

const params = new URLSearchParams({
  id:  "ID-bcd0aa692ce7e6b2",
  uid: "8824a9fc-002d-4fb8-bcea-9e60225a88f0",
  ht:  "identify",
  cid: "customer@example.com",
  ed:  JSON.stringify(customer),
  v:   "api",
  ip:  "203.0.113.42",
  ts:  new Date().toISOString(),
});

await fetch(`https://data.thoughtmetric.io/d?${params}`);

Query parameters

id string, required	Your Project ID.
uid string, required	UUID identifying the visitor. Use the same value as their pageviews and order.
ht string, required	Always `identify` for this call.
cid string, required	Customer ID, usually their email address, but an internal reference works too. This is the de-duplication key, and hits without it are discarded.
ed string	JSON object with the customer details. Fields below.
v string	Always `api` for this call.
ip string	Customer's IP address.
dl string	URL the identify happened on.
rl string	Referring URL.
ts string	Time of the event. ISO 8601 or Unix seconds.

The `ed` object

email string	Customer's email address.
created_at string	Date of the customer's first ever order. Drives the new-versus-returning split.
total_spent number	Lifetime spend to date. Feeds customer LTV reporting.
orders_count number	Lifetime order count to date.
first_name string	First name.
last_name string	Last name.
company string	Company name.
phone string	Phone number.
address1 string	Address line one.
address2 string	Address line two.
city string	City.
state string	State or region.
zip string	Postal code.
country string	Country.
external_id string	Your own identifier for the customer.

Example `ed` payload

ed (before URL encoding)

{
  "email": "customer@example.com",
  "created_at": "2022-09-06 20:12:44 -0400",
  "total_spent": 455.00,
  "orders_count": 3,
  "first_name": "Ada",
  "last_name": "Lovelace"
}

Notes

If your project has PII anonymization enabled, emails and names are hashed on arrival and will not come back from the REST API.
total_spent and orders_count are lifetime figures you supply. We do not accumulate them, so send the running totals including the current order.