/conversions API Endpoint

The /conversions endpoint returns a list of all conversion events that occurred within a given timeframe, along with contextual metadata such as the conversion page, previous page, timestamp, and the type of conversion (e.g., HubSpot form, custom event).

This API is designed to help you audit and analyze actual user conversions across your marketing funnel. It supports filtering by attribution source, landing page, conversion page, and even specific conversion types — making it easy to isolate the conversions that matter most.

By exposing raw conversion data in a structured format, the /conversions endpoint gives you a reliable, API-accessible source of truth for measuring marketing performance. You can use it to:

Track which campaigns or sources are driving real conversions — not just traffic
QA form events or custom triggers across different pages and domains
Reconcile backend conversions with client-side events for accuracy
Build dashboards that visualize conversion timing, paths, and types

Whether you're validating integrations, debugging funnel drop-offs, or building a reporting layer — the /conversions endpoint gives you clean access to every tracked conversion event.

Request


1POST /api/v1/conversions  
2Authentication: YOUR_API_KEY  
3Content-Type: application/json

Query Parameters

These parameters allow you to filter the conversions returned by the query.

All filters are optional and use exact match logic. You can combine multiple filters to narrow results; all filters are applied using AND conditions.

Unless otherwise specified, the query defaults to a 30-day time window.

Parameter	Type	Description
offset	int	Offset for batch-based pagination (default: 0)
start_date	string (ISO 8601 or YYYY-MM-DD)	Start of the time window to analyze. Only conversions that start on or after this date are included. Example: 2025-07-01T23:59:59Z or 2025-07-01
end_date	string (ISO 8601 or YYYY-MM-DD)	End of the time window to analyze. Only conversions before or on this date are included. Example: 2025-07-31T23:59:59Z or 2025-07-31.
conversion_page	string	Filter to conversions that occurred on a specific page URL. Must be the exact URL tracked during conversion.
meta_type	string	Filter by the type of conversion. Supports values like hubspot_form, custom, or html_form.
meta_id	string	Filter by a specific conversion ID (e.g., a HubSpot form ID or custom event ID).
source	string	Filter by traffic source (e.g., google.com, facebook.com, example.com) Matches against the full primary domain. If utm_source is present, it overrides the derived source.
medium	string	Filter by traffic medium (e.g., cpc, organic). If utm_medium is present, it overrides the derived medium.
campaign	string	Filter by UTM campaign name.
content	string	Filter by UTM content value.
term	string	Filter by UTM term value.
landing_page	string	Filter by the landing page URL (e.g., https://example.com/pricing, https://store.example.com/products/xyz).

Example: Filter by Time Window


1POST /api/v1/conversions
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "start_date": "2025-07-15",
7  "end_date": "2025-07-30",
8}

Returns all conversions between July 15th, 2025 and July 30th, 2025

Example: Filter by Conversion Point


1POST /api/v1/conversions
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "conversion_page" : "https://www.example.com/request-a-demo/",
7  "meta_id" : "request-a-demo-form",
8  "meta_type" : "html_form"
9}

This request returns all html_form conversions that occurred on the page "https://www.example.com/request-a-demo/" using the specific form or event ID request-a-demo-form.

Response


1{
2  "records": [
3    {
4      "email": "[email protected]",
5      "timestamp": "2025-03-05 15:14:00",
6      "conversion_page": "https://testdomain.com/thankyou",
7      "previous_page": "https://testdomain.com/pricing",
8      "conversion_meta": {
9        "type": "html_form",
10        "id": "lead-capture-form-1"
11      }
12    },
13    {
14      "email": "[email protected]",
15      "timestamp": "2025-03-05 14:31:00",
16      "conversion_page": "https://testdomain.com/purchase-complete",
17      "previous_page": "https://testdomain.com/cart",
18      "conversion_meta": {
19        "type": "custom_event",
20        "id": "purchase-complete"
21      }
22    }
23  ],
24  "pagination": {
25    "records_processed": 200,
26    "total_records": 427,
27    "has_more": true
28  }
29}

Sample Response Highlights

Each conversion record represents a unique conversion event that meets the filter criteria. Each page can contain up to 50 records. Use the pagination object to request additional pages of results.

Conversion records may include the following fields:

email

The user’s email address, if captured during the conversion. This can be used to connect AttributionHub data with external contact records.

timestamp

When the session started (ISO 8601 UTC format).

conversion_page

The full URL of the page where the conversion event was triggered. Can be used to identify what conversion was completed.

previous_page

The page the user visited just before the conversion occurred. The previous page can help identify content the user was interested in before the conversion, which can help identify what content is converting.

conversion_meta

Metadata associated with the conversion event.

type

The kind of conversion (hubspot_form, custom_event, html_form, etc.) completed. Useful to distinguish between different types of conversions

The conversion point identifier. Used to differentiate between different conversions of the same type.

pagination

The /conversions endpoint uses batch-based pagination to return up to 50 conversion records per request. Each response includes a pagination object that helps you request additional pages of results efficiently. The meaning of offset, records_processed, and total_records depends on whether session-level filters (such as source, medium, or landing_page) are applied.

Without Session Filters (Direct Conversion Query)

When no session-level filters are included in the request, the API queries conversion records directly. In this case, the offset parameter refers to the number of conversion records to skip. Each request will return up to 50 matching conversions, and you can paginate by increasing the offset value in increments of 50.

With Session Filters (Attribution-Based Query)

When session filters are applied, the API first finds sessions that match your filter criteria, then retrieves all conversions associated with those sessions. In this case, offset refers to the number of sessions that have been processed — not the number of conversions. The API processes sessions in batches of 200 and continues processing until it collects 50 or more conversion records from each batch or exhausts the session pool. To request the next page of results, set offset to the records_processed value returned from the previous response.

records_processed

Represents the number of records scanned to produce the current response. This value should be used as the offset for the next request. Its meaning changes depending on filter type — it reflects conversion records in a direct query and session records in a session-filtered query.

total_records

The total number of matching conversions (in a direct query) or matching sessions (in a session-filtered query), based on the filters and time range provided.

has_more

A boolean value that indicates whether additional pages of results are available. If true, increase the offset in your next request to retrieve more data.

No Results

If no qualifying conversions are found, the API will return:


1{ "message": "No conversions matched the given filters." }

This is not an error; it simply indicates no users matched the filters.

← /sessions API Endpoint /pages API Endpoint →