Thribee Conversion Tracking API — Server-to-Server

Version: 0.5 (Draft for Clients) 
Last updated: December 17th, 2025

1. Overview

Thribee is currently working on a server-to-server (S2S) conversion tracking alternative. This solution is not yet available in production.

We are sharing this technical documentation in advance to explain the intended approach and to collect early feedback from our partners before starting development.

Once implemented, this solution will allow clients to send conversion events directly from their backend systems to Thribee via a secure API.

Expected advantages:

• Higher accuracy in environments with cookie restrictions or ad-blockers

• Improved data privacy and control

• Browser-independent tracking

• Full alignment between client-side metrics and Thribee reporting

2. Requirements

To use this API, you will need:

📌 If a partner does not have an S2S token configured, Thribee will not append the thribee_click_id parameter to outbound URLs.

📌 If you are already using an authentication token for the Thribee Metrics API, please note that it is still to be decided whether the same token will be reused for the Conversions API or if a separate token will be required. This decision will be validated during the design phase.

3. Click Attribution

Thribee appends a unique click identifier to every outbound link:

https://www.yoursite.com/listing/123?thribee_click_id={CLICK_ID}&utm_source=lifull-connect&utm_medium=CPC&utm_campaign={CAMPAIGN_NAME}

• thribee_click_id will be an alphanumeric string

📌 If you already use a similar parameter name and need custom naming, contact your Account Manager.

4. Sending Conversion Events

Endpoint

POST https://api.thribee.com/tracking/conversions

(Host may change depending on infrastructure; any change will be communicated beforehand.)

Required Headers

5. Request Body

Required Fields

JSON Example

{
  "thribeeClickId": "9fd7a992-4600-43e5-9ccd-1387bb1548f3",
  "listingId": "ABC-123456",
  "timestamp": "2025-07-21T11:29:12.697Z"
}

6. Optional Fields

Conversion Type (type)

Indicates the type of conversion being reported.

Accepted values:

• form

• phone

• whatsapp

• financing

• subscription

• other

Additional values may be introduced based on partner feedback.

Example use cases for score

• Clients for whom different conversion types (form, phone, etc.) do not have the same business value

• Clients using attribution models other than last-click (e.g. weighted or multi-touch models)

JSON Example:

{
  "thribeeClickId": "9fd7a992-4600-43e5-9ccd-1387bb1548f3",
  "listingId": "ABC-123456",
  "timestamp": "2025-07-21T11:29:12.697Z",
  "type": "form",
  "score": 0.75,
  "metadata": "SERP"
}

7. Response Messages

Example Success Response:

{
  "status": "success",
  "data": {
    "receivedAt": "2025-07-21T11:29:12.697Z"
  }
}

8. Validation Rules

• Token must be associated with a configured partner → 401 Unauthorized

• Invalid timestamps will be rejected → 400 Bad Request

• thribeeClickId must be valid and match a known click within the maximum time window (to be defined) → 404 Not Found

• type must match an approved value. Else, the conversion will be flagged as other

9. FAQs

Can conversions be tracked without thribeeClickId? 
No, such requests are rejected.

Will the pixel continue to work? 
This is especially relevant when transitioning from pixel-based tracking to server-to-server tracking. Both solutions can coexist. However, once you are satisfied with your implementation of server-to-server tracking, you may remove the Thribee tracking pixel from your website.

What if I rotate my token? 
Only the newest token will be accepted.

Can a click on one listing trigger a conversion for another? 
Yes, attribution follows the original click event. Even if the user keeps browsing your website and going from one listing to another, we need the original thribee_click_id from when we sent the user to your website.

Will you offer any alternatives to use server-to-server tracking other than direct API integration? 
In a first stage, we will support clients that use our Conversions API directly. Later on, we plan to offer additional ways to implement server-side-tracking.