---
title: Event Tracking & Analytics
slug: event-tracking-and-analytics
docTags: 
createdAt: 2026-03-25T01:31:59.677Z
---

The Events API provides transparency into how helpline information is displayed to and used by end users. This feature captures two discrete, timestamped signals to measure the user journey: 

- `helplineDisplay`**:** Captures when a helpline is shown to a user.
- `helplineClick`**:** Captures when a user takes action to contact a helpline.

### Key Benefits

- **Billing Transparency:** Provides transparency for ThroughLine and customers to ensure billing is based on verified usage data.
- **Compliance & Impact Reporting:** Through exportable analytics, simplifies reporting to regulators and stakeholders based on documented reach and user activity.
- **Load Management:** Allows ThroughLine to monitor and manage load across helplines to ensure service availability.
- **Conversion Insights:** Uses a unique identifier to calculate the click-through rate (CTR) from display to contact.

### Data Flow

The following diagram illustrates how event data travels from your application to the ThroughLine analytics dashboard.

```mermaid
%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "Lato, system-ui, sans-serif",
    "fontSize": "15px",
    "lineColor": "#9ba3aa",
    "primaryTextColor": "#0f2027",
    "clusterBkg": "#ffffff",
    "clusterBorder": "#c2c9cc",
    "edgeLabelBackground": "#ffffff"
  },
  "flowchart": {
    "curve": "basis",
    "nodeSpacing": 60,
    "rankSpacing": 75,
    "padding": 18,
    "htmlLabels": true
  }
}}%%
flowchart TB
    client("<b>Client application</b><br/><span style='color:#5c6f77'>Partner system / 3rd-party integration</span>")

    subgraph throughline["&nbsp;ThroughLine systems&nbsp;"]
        direction TB
        display("<b>POST /v2/events/helplineDisplay</b><br/><span style='color:#5c6f77'>helplineId + sessionId + timestamp</span>")
        clickEvt("<b>POST /v2/events/helplineClick</b><br/><span style='color:#5c6f77'>+ contactMethod required</span>")
        dashboard("<b>Dashboard</b><br/><span style='color:#5c6f77'>Looker dashboard with CSV export</span>")
    end

    client -->|"Display"| display
    client -->|"Click"| clickEvt
    display --> dashboard
    clickEvt --> dashboard

    %% ── ThroughLine brand styling ──
    classDef entry fill:#ede9e1,stroke:#d8d1c4,color:#0f2027,rx:12,ry:12;
    classDef api   fill:#eef4f6,stroke:#7bb5b9,color:#0f2027,rx:12,ry:12;
    classDef dash  fill:#dcebec,stroke:#2b8e94,color:#0f2027,stroke-width:1.5px,rx:12,ry:12;

    class client entry;
    class display,clickEvt api;
    class dashboard dash;

    style throughline fill:#fbfdfe,stroke:#c2c9cc,stroke-width:1.5px,stroke-dasharray:6 5;

    %% coral for user-initiated events, teal for internal flow
    linkStyle 0,1 stroke:#e8886c,stroke-width:2.5px;
    linkStyle 2,3 stroke:#2b8e94,stroke-width:2.5px;
```

### Events Endpoints

These endpoints are used to report the two core signals. Detailed schemas are available in [the API Reference](docId\:S7XVE1bI_GhsILgtI9CzM).

| **Method** | **Endpoint**                 | **Required Parameters**                                                                                                   | **Description**                                            |
| ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| POST       | `/v2/events/helplineDisplay` | `helplineId (string)`<br /><br />`sessionId (string)`<br /><br />`timestamp (ISO 8601)`                                 | Report when a helpline is displayed to a user.             |
| POST       | `/v2/events/helplineClick`   | `helplineId (string)`<br /><br />`sessionId (string)`<br /><br />`timestamp (ISO 8601)`<br /><br />`contactMethod (enum)` | Report when a user clicks a contact method for a helpline. |

**Parameter Definitions**

The Events API utilizes two primary identifiers to link these signals:

- `helplineId`: This string must match the unique ID for the helpline entity retrieved from the /helplines endpoint.
- `sessionId`: An opaque string provided by the client to link a "display" event to a "click" event.
  - **Flexibility**: You may use any identifier you prefer, such as a GUID or a hashed string.
  - **Consistency**: The ID must remain unique and consistent for the duration of a single user session to allow for accurate conversion rate calculations.
  - **Anonymity**: Because this ID is partner-provided and contains no PII, it ensures user anonymity while still providing measurable impact tracking.

**Contact Method Values**

The `contactMethod` field is an enum used to report which specific channel a user chose to contact.

| <font color="#0C121D"></font> | <font color="#0C121D"></font> |
| ----------------------------- | ----------------------------- |
| phone                         | Phone call                    |
| sms                           | SMS / text message            |
| onlineChat                    | Online chat                   |
| website                       | Visit to the website          |
| tty                           | TTY / relay call              |
| whatsapp                      | WhatsApp                      |
| reportingForm                 | Online reporting form         |

### Privacy & Quota Information

- **No Personal Data:** No personally identifiable information is collected at any stage.
- **Service-Level Data:** Events record what happened (helpline ID), how (click), and when (timestamp). Never who.
- **Quota Exemption:** Event API calls do not count against the standard API display quota.

### Batch Upload

We also support batch event uploads, which is useful if you’re unable to deliver events in real-time. This is an asynchronous process, consisting of an initial upload followed by a status poll:

| **Method** | **Endpoint**                   | **Body content**                                      | **Description**                                                                |
| ---------- | ------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
| POST       | `/v2/events/batch`             | An array of helplineDisplay and helplineClick events. | Upload up to 1M/150MiB of events (whichever is smaller) and receive a job ID.  |
| GET        | `/v2/events/batch/jobs/:jobId` | None                                                  | Get the in-progress status or the terminal result.                             |

Once the job is complete, the status payload will tell you how many events were valid, how many failed validation, and what was wrong with each of them. More details are available in [the API Reference](docId\:Pm_XObDZfL1J7tWjpZRvI).

By default, valid events are stored and invalid events are rejected; you should investigate and fix the failures and then re-submit them individually. It’s important in this default mode that you don’t re-submit events that were accepted, as they will cause duplication in your reporting.

However if you’d prefer, you can specify on upload that the batch be treated atomically: in this mode, even one failure will reject storage of the entire batch, allowing you to fix the errors and then resubmit the entire payload without risk of duplication.