What's the difference between the 'Agent' and 'Default' hosted experiences?
The Carrier Platform API supports two bridge experiences: "HostedX" and "AgentX," the upgraded Root Agent Portal. This document explains both, when to use each, and how link lifetime and redirect behavior differ between them.
Root offers a variety of "hosted experiences" like our direct-to-consumer HostedX, and agent-facing AgentX portal (traditionally known as Root Agent Portal, or RAP). At any point during a customer or agent's quoting lifecycle, an integration may "bridge" or redirect the customer to a hosted Root property by creating a bridge link using a declared experience.
What is a bridge link?
A bridge link is a URL you generate via the CP API that redirects a user (or an agent's client) into Root's quoting and binding flow. The URL contains a short-lived authentication token so Root can identify the quote without requiring the user to log in again.
You create a bridge link by calling [POST] Create Bridge Link:
POST /v3/quoting/quote/{quote_id}/bridge_link
The experience field in the request body controls which of the two bridge experiences is used.
The two experiences
"default" — Direct-to-Consumer HostedX embedded consumer flow
experience: "default" (or omit the field entirely)
This is the standard self-service consumer flow, powered by Root's HostedX embedded application.
| Property | Behavior |
|---|---|
| Who uses the link | The end customer (direct-to-consumer) |
| cancelUrl / successUrl | Used. Set these to redirect the customer after they cancel or successfully bind. |
| Link lifetime | The token expires based on ttlHours (default 24 hours, min 1, max 48). After expiry the link is invalid. |
| Link reuse | Single-use by default. Once the customer follows the link and it is authenticated, the token is consumed. |
| Where the user lands | Root's HostedX web application at the PARTNER_BRIDGE_BASE_URL |
When to use: When your integration hands the link directly to the customer (e.g., embedded in an email, redirect after a quote form, or embedded iframe).
Example request:
POST /v3/quoting/quote/{quote_id}/bridge_link
{
"experience": "default",
"cancelUrl": "https://www.yoursite.com/insurance/canceled",
"successUrl": "https://www.yoursite.com/insurance/thank-you",
"ttlHours": 24
}"agent" — AgentX / Root Agent Portal (RAP) flow
experience: "agent"
This experience targets agent-assisted flows. The bridge link is consumed by the Root Agent Portal (RAP) back-end, not directly by the end customer.
| Property | Behavior |
|---|---|
| Who uses the link | An agent in the Root Agent Portal, acting on behalf of a client |
| cancelUrl / successUrl | Not used. These fields are accepted by the API but are ignored. The agent portal controls its own navigation. |
| Link lifetime | The token has a ttlHours-based expiry like the default experience, but agent bridge links are multi-use. This means the token is not consumed on first authentication and can be reused until it expires. |
| Link reuse | Multi-use. The same link/token can be authenticated multiple times within its TTL. |
| Where the user lands | The Root Agent Portal at the HOST_NAME/agent_api endpoint |
When to use: When your integration is routing through agents or brokers who initiate the quote and then hand the experience off to the client using Root's agent tooling.
Example request:
POST /v3/quoting/quote/{quote_id}/bridge_link
{
"experience": "agent",
"ttlHours": 48
}Which experience should I use?
| Your use case | Experience to use |
|---|---|
| Customer self-service | "default" |
| You need cancelUrl / successUrl redirects | "default" |
| Agent-assisted flow | "agent" |
| Link needs to be reusable within its TTL | "agent" |
If you are unsure, start with "default". The "agent" experience requires the BRIDGE_TO_ROOT_AGENT_PORTAL_ENABLED feature flag to be enabled for your integration.
Contact your Root representative if you need agent experience access.
Link lifetime and TTL
Both experiences support the ttlHours parameter:
- Minimum: 1 hour
- Maximum: 48 hours
- Default: 24 hours
Default experience: Token is consumed on first authentication. Once expired, you must generate a new bridge link.
Agent experience: Multi-use. The same link can be followed multiple times within the TTL window. Once expiresAt is reached, a new bridge link must be generated.
Create Bridge Link API reference summary
URL POST /v3/quoting/quote/{quote_id}/bridge_link
Request body:
| Field | Type | Default | Notes |
|---|---|---|---|
experience | "default" or "agent" | "default" | Selects the bridge experience |
cancelUrl | string (URI) | — | Default experience only |
successUrl | string (URI) | — | Default experience only |
ttlHours | integer (1-48) | 24 | Token lifetime in hours |
attributionParameters | object | — | Pass-through attribution data |
Response (201 Created):
| Field | Notes |
|---|---|
bridgeId | UUID identifying this bridge link |
url | The full bridge URL to use |
token | The raw token embedded in the URL |
expiresAt | ISO 8601 timestamp when the token expires |
experience | The experience value used (echoed back) |
Updated 12 days ago