APIs

Journey API

The Journey API gives your backend access to the evaluation activity Jourvex observed across sessions. Use it when a visitor converts and you want to push their evaluation context into your CRM, warehouse, or internal systems before your team ever speaks to them.

What this unlocks

The State API tells you what kind of evaluator is on your site right now. The Journey API gives you the broader evaluation context behind that session.

When a visitor books a demo or starts a trial, your backend can fetch the evaluation activity Jourvex observed across sessions: pages viewed, session timing, engagement signals, conversion events, and recommendation context.

That context can be attached to CRM records, warehouse events, Slack alerts, or internal workflows before your first sales conversation happens.

The goal is simple: preserve evaluation context between the anonymous visit and the identified lead record so your team has useful context before outreach begins.

How it works

The Journey API is called from your backend, never from the browser. Your API key stays on your server. The journey_id comes from the state object that already resolved in the browser while the visitor was active on your site.

1
Visitor converts on your site

They book a demo, start a trial, or submit a form. At this point the state object is already available in memory from earlier page activity.

2
Your frontend sends journey_id to your backend

On form submit, include journey_id alongside the rest of your form payload.

3
Your backend fetches the journey

Your server calls the Journey API using your API key and the provided journey_id. Jourvex returns the reconstructed journey object and aggregated evaluation context.

4
Push it anywhere

Send the journey data into HubSpot, Salesforce, Snowflake, BigQuery, Slack, or your own internal systems. Use journey_id as your stable deduplication key downstream.

Making a request

HTTP 
GET https://api.jourvex.com/api/journey/{journey_id}

Authorization: Bearer jvx_live_...

Python example

python 
import requests

def fetch_journey(journey_id: str) -> dict:
    res = requests.get(
        f"https://api.jourvex.com/api/journey/{journey_id}",
        headers={
            "Authorization": f"Bearer {YOUR_API_KEY}"
        }
    )

    res.raise_for_status()
    return res.json()

Node.js example

javascript 
async function fetchJourney(journeyId) {

  const res = await fetch(
    `https://api.jourvex.com/api/journey/${journeyId}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.JOURVEX_API_KEY}`
      }
    }
  );

  if (!res.ok) {
    throw new Error(`Journey fetch failed: ${res.status}`);
  }

  return res.json();
}
Store your API key as an environment variable. Never expose API keys in browser code or client-side bundles. See API Keys for generation and rotation guidance.

Response schema

The full shape of the journey object returned by the API.

Fields may expand over time as Jourvex adds new evaluation signals and journey metadata. Existing top-level fields are designed to remain backwards compatible.

Journey response — full schema 
{
  "journey_id": "cluster_8f2ab",
  "first_seen": "2026-05-07T09:14:22Z",
  "last_seen": "2026-05-21T16:03:11Z",
  "converted": true,

  "sessions": [
    {
      "session_id": "sess_1",
      "start": "2026-05-07T09:14:22Z",
      "end": "2026-05-07T09:17:46Z",
      "duration_sec": 204,
      "pages": ["/home", "/features", "/about"],
      "clicks": 8,
      "scrolls": 15,
      "channel": "linkedin",
      "conversions": [],
      "external_redirects": []
    }
  ],

  "metrics": {
    "total_sessions": 12,
    "total_time_seconds": 6486,
    "total_clicks": 116,
    "total_scrolls": 262,
    "avg_gap_hours": 28.4
  },

  "intent": {
    "score": 88,
    "level": "high",
    "signals": {
      "pricing_views": 4,
      "high_intent_hits": 9,
      "enterprise_hits": 1,
      "days_since_last_seen": 0,
      "conversion_hits": 1
    }
  },

  "recommendation": {
    "flag": "post_conversion_context",
    "card": {
      "headline": "This evaluator already converted",
      "what_is_happening": "...",
      "what_to_do": "...",
      "why_it_matters": "..."
    }
  },

  "live": {
    "is_active": true,
    "current_page": "/pricing",
    "last_event_ts": "2026-05-21T16:03:11Z"
  }
}

Field reference

Field
Type
Description
journey_id
string
Stable identifier for this evaluator journey. Use this as your downstream deduplication key.
sessions
array
Ordered session activity observed across the journey, including pages viewed, engagement metrics, channels, and conversion-related events.
metrics
object
Aggregated totals across all observed sessions.
intent
object
Current intent score, level, and contributing signals.
recommendation
object
Recommended next-step context generated from the observed evaluation pattern.
live
object
Current activity state including whether the evaluator is active, their latest observed page, and most recent event timestamp.

Full workflow example

This example shows the complete browser → backend → CRM flow.

Browser side — capture journey_id

javascript 
window.jourvex.on("stateReady", function(journey) {

  document
    .getElementById("demo-form")
    .addEventListener("submit", function() {

      fetch("https://your-backend.com/demo-booked", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        keepalive: true,
        body: JSON.stringify({
          journey_id: journey.journey_id,
          intent_state: journey.intent_state,
          archetype: journey.archetype
        })
      });

    });

});

Backend — fetch full journey

python 
import requests

@app.post("/demo-booked")
async def demo_booked(data: dict):

    journey_id = data["journey_id"]

    journey_res = requests.get(
        f"https://api.jourvex.com/api/journey/{journey_id}",
        headers={
            "Authorization": f"Bearer {JOURVEX_API_KEY}"
        }
    )

    journey = journey_res.json()

    hubspot.update_contact({
        "jourvex_intent_score": journey["intent"]["score"],
        "jourvex_intent_level": journey["intent"]["level"],
        "jourvex_sessions": journey["metrics"]["total_sessions"],
        "jourvex_first_seen": journey["first_seen"],
        "jourvex_pricing_views": journey["intent"]["signals"]["pricing_views"]
    })

Rate limits and usage

Endpoint
Limit
Notes
GET /api/journey/{journey_id}
300 per hour
Per API key.

Use journey_id as your stable deduplication key across downstream systems.

← State API API Keys →