Urlicer API v1

Conversion events

Tell Urlicer when a visitor signs up or buys, and see which links brought them.

Clicks tell you who opened a link. Conversion events tell you what they did next: signed up, started a trial, paid. Your server sends each event to Urlicer, Urlicer works out which short link the visitor came through, and the workspace dashboard and each link's analytics show conversions, the conversion rate and revenue next to the clicks.

Nothing runs in the visitor's browser. Events come from your backend or from a payment provider's webhook, with an API key.

Before you start

  • Plan. Conversion tracking is on the Team plan (250,000 events a month) and the Business plan (no monthly limit). The month is the calendar month in UTC.
  • Turn it on. The owner or an admin turns it on under Settings > Tracking, and picks which event names count as conversions (signup and purchase by default), after ticking a box that confirms what it does. Until it is on, events are refused with 403 feature.
  • A key. Any API key of the workspace can send events. For a server that only reports events, create a key with Events only ticked on the Developers page: it can send and erase events and read the workspace, and cannot touch links.

How an event finds its link

With tracking on, every redirect through one of the workspace's links adds a ulink parameter to the destination URL, for example https://example.com/pricing?ulink=go.example.com:spring. A single link can opt out in its own settings. Each event is then matched in this order:

  1. The visitor. If you send the visitor's IP address and User-Agent, Urlicer looks for that visitor's last click on one of your links in the two days before the event. Inside the link named by link, when you send one.
  2. The link. If no click is found but you sent link, the event is credited to that link.
  3. The customer. If neither is there but you sent a customerRef that an earlier, matched event of this workspace carried, the event goes to that earlier event's link. This is how a purchase made a week after the signup still counts for the link that brought the signup.
  4. Nothing. The event is stored as unattributed. It counts for no link, and the workspace report says how many such events it left out.

Send everything you have. The link value is the most reliable on its own: keep ulink from the landing URL in the visitor's session and send it with their events.

Send an event

POST /api/v1/events

Report a signup, a purchase or any other named event. Urlicer matches it to the link it came from and adds it to the reports.

Body fields
Field Type Required Description
name string required What happened, for example "signup" or "purchase". Up to 64 letters, digits and "_", "-", "." or ":". Which names count as conversions is set in the workspace settings; other names are stored and listed too.
idempotencyKey string required Your own unique id for this event, up to 128 characters: an order id, a payment id, a webhook event id. Sending the same key again returns the first event and stores nothing new, so retries are safe. Kept for 7 days.
value number optional The amount, in the currency's main unit (49.90, not 4990), from 0 to 1,000,000,000. Needs currency.
currency string with value Three-letter ISO 4217 code, for example "EUR". Revenue is reported per currency and never converted.
occurredAt integer optional When it happened, in unix seconds UTC. Defaults to now. Accepted from 30 days back to 5 minutes ahead.
customerRef string optional Your own id for the customer, up to 128 characters. A later event with the same customerRef, such as a purchase days after the signup, is credited to the link the customer's earlier event came from. Do not send an email address or a name.
link string optional The value of the ulink parameter the visitor arrived with, for example "go.example.com:spring". Credits the event to that link.
visitorIp string with visitorUserAgent The visitor's IP address as your server saw it. Hashed on arrival and never stored; used to find the visitor's click.
visitorUserAgent string with visitorIp The visitor's User-Agent header, up to 1,024 characters. Hashed together with the IP address.
Request
curl -X POST "https://urlicer.com/api/v1/events" \
  -H "Authorization: Bearer url_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "purchase", "idempotencyKey": "order-1042", "value": 49.9, "currency": "EUR", "customerRef": "user-381", "link": "go.example.com:spring"}'
Response
{
  "id": "evt_3f9c2a71d04be5a8c6e1",
  "duplicate": false
}
Response fields
Field Type Description
id string The event's id.
duplicate boolean true when this idempotencyKey was sent before: the answer is the first event's id, with status 200, and nothing new is stored. A new event answers 202.
  • The event is queued and matched within about ten seconds. If it names a visitor whose click has not been processed yet, matching is tried once more two minutes later.
  • An event that matches no link is still stored, as unattributed, and the reports say how many there are. It is not an error.
  • 403 feature: conversion tracking is off for the workspace; upgrade is true when the plan does not include it, false when it only needs turning on. 403 scope: the key cannot send events. 403 quota: the workspace has sent its plan's events for this month (UTC); a duplicate is still answered, so retries never hit it. 400 validation lists every problem with the body.

Example: a signup

Keep ulink when the visitor lands, and send the event when the account is created. The visitor's IP address and User-Agent come from the same request.

// On the landing page: keep the link the visitor came through.
if (isset($_GET['ulink'])) {
    $_SESSION['ulink'] = $_GET['ulink'];
}

// When the account is created:
$ch = curl_init('https://urlicer.com/api/v1/events');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer url_live_YOUR_EVENTS_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'signup',
        'idempotencyKey' => 'signup-' . $user->id,
        'customerRef' => 'user-' . $user->id,
        'link' => $_SESSION['ulink'] ?? null,
        'visitorIp' => $_SERVER['REMOTE_ADDR'],
        'visitorUserAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    ]),
]);
curl_exec($ch);

Example: a Stripe payment

Send purchases from your Stripe webhook, not from the success page, so a closed tab never loses a sale. Stripe gives amount_total in the smallest currency unit, so divide it by 100 for EUR or USD. Stripe's lower-case currency codes are accepted. The webhook event id makes a good idempotencyKey: Stripe may deliver the same event more than once.

// When you create the Checkout Session, pass your user id:
//   client_reference_id: String(user.id)

// In your Stripe webhook handler, after verifying the signature:
if (event.type === "checkout.session.completed") {
  const session = event.data.object;
  await fetch("https://urlicer.com/api/v1/events", {
    method: "POST",
    headers: {
      Authorization: "Bearer url_live_YOUR_EVENTS_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "purchase",
      idempotencyKey: event.id,
      customerRef: `user-${session.client_reference_id}`,
      value: session.amount_total / 100,
      currency: session.currency,
    }),
  });
}

Example: a Paddle payment

The same pattern with Paddle's transaction.completed webhook. Paddle's totals are also in the smallest unit.

// At checkout, pass your user id in custom_data: { "userId": "381" }

// In your Paddle webhook handler, after verifying the signature:
if ($event['event_type'] === 'transaction.completed') {
    $tx = $event['data'];
    $ch = curl_init('https://urlicer.com/api/v1/events');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer url_live_YOUR_EVENTS_KEY',
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'name' => 'purchase',
            'idempotencyKey' => $tx['id'],
            'customerRef' => 'user-' . $tx['custom_data']['userId'],
            // details.totals.total is in the smallest unit: cents for EUR and USD.
            'value' => (int) $tx['details']['totals']['total'] / 100,
            'currency' => $tx['currency_code'],
        ]),
    ]);
    curl_exec($ch);
}

Erase a customer's events

DELETE /api/v1/events

Delete every event sent with one customerRef, for example when that customer asks you to erase their data.

Query parameters
Field Type Required Description
customerRef string required The customerRef the events were sent with.
Request
curl -X DELETE "https://urlicer.com/api/v1/events?customerRef=user-381" \
  -H "Authorization: Bearer url_live_YOUR_KEY"
Response
{
  "deleted": "queued"
}
  • Answers 202. The deletion is applied by the database shortly after; it removes the data, not just hides it.
  • Works whether or not conversion tracking is still on. Events still in the queue at that moment are not reached; calling it again catches them.
  • The workspace's audit log records that an erasure happened, without the customerRef.

What the reports count

  • Conversions are events credited to a link whose name is one of the workspace's conversion names. Other names are stored and listed by name, but are not conversions.
  • A visitor matched by their click counts once, however many conversion events they send. Events credited through link or customerRef count one each.
  • Conversion rate is visitors who converted divided by unique visitors in the same period, so it never goes above 100%.
  • Revenue is the sum of value on credited events, shown per currency and never converted between currencies.
  • An event is counted on the day it happened (occurredAt), not the day it was sent.
  • Clicks by bots are never matched, so a bot cannot take credit for a sale.

Privacy

Urlicer sets no cookie for this. The visitor's IP address and User-Agent are turned into a hash, the same one click analytics uses, before the event is queued, and are not stored. customerRef is your own identifier: use an internal id, never an email address or a name.

Whether you need your visitors' consent depends on where they are and on how you use the data: the ulink parameter and the IP address and User-Agent are information read from a visitor's device. Check with your own adviser before you turn this on for visitors in the EU or the UK. To erase one customer's events, use the erase endpoint.