/contacts API Endpoint

The /contacts endpoint returns CRM-style summaries of users who have completed at least one conversion, and match the provided filters — unless you provide a list of emails in which case all matching emails are returned. Each contact record includes attribution metadata, a complete multi-session timeline, and a behavioral summary of engagement and conversion activity.

Use /contacts to:

Enrich CRM or CDP records with detailed contact journey information and insights
Segment users by attribution and conversion behavior for analysis or remarketing
Visualize individual conversion paths across all website sessions
Analyze audience quality, campaign performance, and lead lifecycle metrics
Support BI dashboards, retargeting workflows, and advanced audience analytics

This endpoint is ideal for:

Marketing teams analyzing campaign influence and user behavior across touchpoints
Agencies reporting on multi-touch impact and identifying high-value segments
BI and RevOps teams exploring funnel behavior, engagement patterns, and conversion timelines

Request


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

Query Parameters

These parameters define which contacts are returned, but each contact’s summary is always based on their entire known journey—not just sessions matching the filters.

If emails are provided, all other filters are ignored.

All filters are strict:

Case-sensitive
AND logic: A contact is included only if at least one session matches all specified filters simultaneously. Supplying a list of email addresses disables the filters.

Parameter	Type	Description
offset	int	Used for pagination. When filtering by emails, offset skips ahead in the list of emails. When filtering by time window, offset paginates through the full list of users who had at least one qualifying session and conversion. Use the users_processed value from the response to paginate accurately.
emails	string	Email list to filter by. If provided, disables all other filters
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).
touch_scope	enum	Use in conjunction with other filters to target specific sessions in the user’s journey: • any (default) • first • converting • assist • after any – include all sessions (default) first – only the user's first session converting – sessions where a conversion occurred assist – sessions between first and converting session after - sessions after the first converting session

If you experience timeouts or performance issues, consider reducing the time frame window or making your filters more restrictive.

Example: Filter by Conversion Type (e.g., HubSpot form)


1POST /api/v1/contacts
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "meta_type": "hubspot_form",
7  "meta_id": "638e-2340-45773f-00252"
8}

Returns timelines for contacts who submitted hubspot form 638e-2340-45773f-00252

Example: Filter by touch scope


1POST /api/v1/contacts
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "start_date": "2025-07-15",
7  "end_date": "2025-07-30",
8  "source": "google.com",
9  "landing_page": "https://www.example.com/",
10  "touch_scope": "first"
11}

Returns timelines for contacts whose very first session occurred between July 15th, 2025 and July 30th, 2025, was a referral from Google and landed on the home page.

Example: Advanced conversion and session level filters


1POST /api/v1/timelines
2Authentication: YOUR_API_KEY
3Content-Type: application/json
4
5{
6  "meta_id": "638e-2340-45773f-00252",
7  "source": "google.com",
8  "landing_page": "https://www.example.com/",
9  "touch_scope": "first"
10}

Returns timelines for contacts whose very first session was a referral from Google, landed on the home page, and who converted on conversion point 638e-2340-45773f-00252 during that same session.

Response


1{
2  "contacts": [
3    {
4      "email": "[email protected]",
5      "summary": {
6        "total_sessions": 5,
7        "total_conversions": 1,
8        "conversion_rate_percent": 20,
9        "days_since_last_conversion": 39,
10        "is_repeat_converter": false,
11        "avg_days_between_conversions": null,
12        "avg_days_between_sessions": 1.04,
13        "avg_session_duration_seconds": 660,
14        "days_to_convert": 3,
15        "user_journey": [
16          {
17            "timestamp": "2025-03-01 10:00:00",
18            "source": "paid",
19            "medium": "cpc",
20            "content": "banner1",
21            "campaign": "campaign1",
22            "term": "running shoes",
23            "landing_page": "https://testdomain.com/landing",
24            "exit": {
25              "exit_page": "https://testdomain.com/done",
26              "previous_page": "https://testdomain.com/cart",
27              "timestamp": "2025-03-01 10:11:00"
28            },
29            "session_duration": 660
30          },
31          {
32            "timestamp": "2025-03-04 13:00:00",
33            "source": "paid",
34            "medium": "cpc",
35            "content": "banner2",
36            "campaign": "campaign1",
37            "term": "running shoes",
38            "landing_page": "https://testdomain.com/landing",
39            "conversion": {
40              "email": "[email protected]",
41              "timestamp": "2025-03-04 13:09:00",
42              "conversion_page": "https://testdomain.com/order-confirmed",
43              "previous_page": "https://testdomain.com/checkout"
44            },
45            "session_duration": 540
46          },
47          {
48            "timestamp": "2025-03-05 14:00:00",
49            "source": "organic",
50            "medium": "organic",
51            "content": "none",
52            "campaign": "campaign1",
53            "term": "running shoes",
54            "landing_page": "https://testdomain.com/home",
55            "exit": {
56              "exit_page": "https://testdomain.com/done",
57              "previous_page": "https://testdomain.com/checkout",
58              "timestamp": "2025-03-05 14:16:00"
59            },
60            "session_duration": 960
61          }
62        ],
63        "interested_pages": {
64          "landing_pages": {
65            "https://testdomain.com/landing": 3,
66            "https://testdomain.com/home": 2
67          },
68          "conversion_pages": {
69            "https://testdomain.com/order-confirmed": 1
70          },
71          "exit_pages": {
72            "https://testdomain.com/done": 1,
73            "https://testdomain.com/exit-survey": 1,
74            "https://testdomain.com/thanks": 1,
75            "https://testdomain.com/submitted": 2
76          },
77          "previous_conversion_pages": {
78            "https://testdomain.com/pricing": 1
79          },
80          "previous_exit_pages": {
81            "https://testdomain.com/signup": 2,
82            "https://testdomain.com/cart": 1,
83            "https://testdomain.com/checkout": 1,
84            "https://testdomain.com/get-started": 1
85          }
86        },
87        "first_touch": {
88          "timestamp": "2025-03-01 10:00:00",
89          "source": "paid",
90          "medium": "cpc",
91          "content": "banner1",
92          "campaign": "campaign1",
93          "term": "running shoes",
94          "landing_page": "https://testdomain.com/landing",
95          "exit": {
96            "exit_page": "https://testdomain.com/done",
97            "previous_page": "https://testdomain.com/cart",
98            "timestamp": "2025-03-01 10:11:00"
99          },
100          "session_duration": 660
101        },
102        "converting_touch": {
103          "timestamp": "2025-03-04 13:00:00",
104          "source": "paid",
105          "medium": "cpc",
106          "content": "banner2",
107          "campaign": "campaign1",
108          "term": "running shoes",
109          "landing_page": "https://testdomain.com/landing",
110          "conversion": {
111            "email": "[email protected]",
112            "timestamp": "2025-03-04 13:09:00",
113            "conversion_page": "https://testdomain.com/order-confirmed",
114            "previous_page": "https://testdomain.com/checkout"
115          },
116          "session_duration": 540
117        },
118        "recent_touch": {
119          "timestamp": "2025-03-05 14:00:00",
120          "source": "organic",
121          "medium": "organic",
122          "content": "none",
123          "campaign": "campaign1",
124          "term": "running shoes",
125          "landing_page": "https://testdomain.com/home",
126          "exit": {
127            "exit_page": "https://testdomain.com/done",
128            "previous_page": "https://testdomain.com/checkout",
129            "timestamp": "2025-03-05 14:16:00"
130          },
131          "session_duration": 960
132        }
133      }
134    }
135  ],
136  "pagination": {
137    "records_processed": 200,
138    "total_records": 321,
139    "has_more": true
140  }
141}

Sample Response Highlights

The /contacts endpoint returns an array of contacts that match the provided filter criteria. Each contact includes an email address and a rich summary object containing attribution insights, behavioral patterns, and full session/conversion history. These timelines are based on the user’s entire known journey, not just filtered sessions.

email

The user’s email address. This is typically captured at the time of the first conversion and serves as the primary identifier for contact-level attribution and CRM integration.

total_sessions

The total number of sessions associated with this contact across all time (not just filtered time windows).

Useful for understanding long-term engagement and evaluating how often a user returns.

total_conversions

The total number of conversions completed by the user. Multiple conversions can occur across different sessions or within the same session, depending on the setup.

Great for identifying high-value, highly engaged users.

conversion_rate_percent

The percentage of sessions that resulted in a single conversion.

Useful for assessing user-level conversion efficiency.

conversion_dates

An array of timestamps representing when each conversion occurred.

Helpful for building lifecycle models, analyzing time-to-convert, or syncing with external systems (like CRMs or marketing platforms).

days_since_last_conversion

The number of days since the user’s most recent conversion.

Use this to identify stale leads, monitor reactivation potential, or define active vs. inactive cohorts.

is_repeat_converter

A boolean that returns true if the user has converted more than once.

Great for identifying your most valuable users and measuring repeat conversion behavior.

avg_days_between_conversions

The average number of days between each conversion. Only available if the user has more than one conversion.

Useful for understanding conversion cycles or purchase intervals.

avg_days_between_sessions

The average number of days between sessions for this user.

Helps measure return frequency and can inform retargeting strategies or engagement analysis.

avg_session_duration_seconds

The average time the user spent per session, in seconds.

Useful for gauging session depth, engagement, and potential content stickiness.

user_journey

A full array of session objects that represent the user’s known website activity, including both filtered and non-filtered sessions.

For a breakdown of what is included in each session object, please refer to the sessions API endpoint.

This timeline gives a rich picture of the user’s behavior, attribution path, and engagement patterns. It’s especially helpful for:

Visualizing multi-touch attribution paths
Analyzing drop-off and conversion behavior
Building CRM or BI models that need session-level context

interested_pages

Aggregated page-level insights across all of the user’s sessions. These categories highlight what content or pages the user engaged with before and during key events:

landing_pages – The first page the user landed on in each session

Identifies top entry points and what first captured their interest.

conversion_pages – Pages where a conversion was completed

Shows what experiences or offers triggered form submissions or purchases.

exit_pages – The last page viewed before the user left the site

Can signal drop-off points or content dead ends.

previous_conversion_pages – The page visited just before a conversion

Reveals influential pre-conversion content (e.g., pricing pages, FAQs).

previous_exit_pages – The page viewed right before the user exited

Useful for spotting friction points or underperforming content.

These patterns help marketers, CRO specialists, and content teams:

Identify which content leads to action (or abandonment)
Refine landing experiences to match user intent
Prioritize high-impact pages for testing or personalization

first_touch

The user’s very first recorded session on your site. This touchpoint helps identify the true origin of the user’s journey.

recent_touch

The user’s most recent session. This is helpful to understand the latest interaction.

converting_touch

The session in which the user first converted. Helps identify which touchpoint drove conversion.

Each of these touchpoints is a full session object and may include the following properties:

timestamp: When the session began
source, medium, campaign, term, content: Attribution metadata
landing_page: The first page visited in the session
session_duration: Total duration of the session in seconds
conversion (if applicable):
- conversion_page: Page where the user converted
- previous_page: Page before the conversion
- timestamp: When the conversion occurred
- conversion_meta:
- - type: The kind of conversion (hubspot_form, custom, html_form, etc.) completed. Useful to distinguish between different types of conversions
  - id: The conversion point identifier. Used to differentiate between different conversions of the same type.
exit (if applicable):
- exit_page: The last page visited
- previous_page: Page visited just before exiting
- timestamp: When the user exited

Pagination

The /contacts endpoint uses offset-based pagination and supports two different modes depending on how you request data:

When Emails Are Provided

If the request includes a list of emails, the API paginates directly through that list. The offset parameter determines which position in the submitted list to begin from. Each request returns up to 50 contacts starting at the specified offset. To request the next page of results, use the records_processed value returned in the previous response as the new offset.

When Emails Are Not Provided

If no emails are included in the request, the API dynamically generates a list of contacts based on users who had session activity during the specified time range. The offset in this case refers to the number of session records scanned. The API queries sessions in batches of 200 and collects known contacts (users who have conversion records) from those sessions. It continues this process until it gathers 50 qualifying contacts or exhausts available matches. To paginate, pass the records_processed value from the previous response as the next offset.

records_processed

Indicates how many emails or session records were scanned to produce the current response. This value should be used as the offset in the next request.

total_records

The total number of matching emails (if provided) or matching sessions (if emails are not provided), based on the filters and time range supplied.

has_more

This field is a boolean that indicates whether additional pages of contacts are available. If true, make another request using an updated offset to continue retrieving results.

No Results

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


1{ "message": "No contacts found for the given parameters." }

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

← REST API Overview /sessions API Endpoint →