🔒

Faye <> TravelJoy

Enter the shared password to view.

Faye <> TravelJoy · Referral partnership

Enhanced Partners V2

A cleaner way to sell on behalf of your agencies: referrals move off UTM tags and onto real IDs and a parent-company link — so every sale is attributed, and commissioned, correctly.

From labels → IDs Agencies, self-serve via /enhanced-partners Agency commission + TravelJoy cut
What changes in V2

From UTM labels to IDs + parent company.

V1 inferred the selling agency from a utm_source label the request carried — a free-text string matched against a fixed list. V2 drops the label entirely: each advisor is registered against their agency once, and every sale simply carries that company-scoped advisor ID — validated against TravelJoy's parent-company link.

V1 · todayMatch a label, then translatefragile · string-matched
utm_source label"world-via"
→
Match a whitelistfixed list of agencies
→
Translate the advisorinternal id → agency id
→
Attributeoverride + commission
V2 · newOne company-scoped advisor IDexplicit · validated
advisorIdcompany-scoped · from /v1/advisor
→
Validate parent-company linkis TravelJoy allowed to sell for it?
→
Attributeresolved advisor + commission
🔗

The parent-company link

TravelJoy is the parent; each agency it sells for is a company linked beneath it. That link is the single source of truth for “who can TravelJoy sell for” — it replaces the hardcoded whitelist, and it’s exactly what /enhanced-partners returns, each company with the advisor IDs you’ve created for it. No UTM string is ever consulted.

How a referral works

Look up the ID, refer, get paid.

Each advisor is registered against their agency once — so every sale just carries that advisor ID, and it's attributed to the right place.

1

Look up the advisor ID

Call GET /enhanced-partners for your companies, each with the advisorIds you've created for it.

2

Refer

Send that advisorId on the quote & purchase. The agency is already baked in — no company field needed.

3

Get paid

The agency earns its commission and TravelJoy earns its cut — attributed automatically.

API
# 1 · register an advisor for a company — referredCompanyId is optional, and mints the advisorId
POST /v1/advisor  { "firstName": "Dana", "lastName": "Levi", "referredCompanyId": 657 }
→ { "advisorId": "011238fa-a0cf-4275-88dd-ed7bfe4211ef" }

# 2 · list your companies with the advisor IDs you created for each
GET /enhanced-partners
[
  { "companyId": 657, "name": "TPI", "advisorIds": ["011238fa-…"] },
  { "companyId": 412, "name": "World Via", "advisorIds": ["7c2a…"] }
]

# 3 · refer the sale — just the advisorId
POST /v1/quote   { "advisorId": "011238fa-a0cf-4275-88dd-ed7bfe4211ef" }
Advisor attribution

Created once, reused every time.

The same logic in V1 and V2 — so an advisor’s commissions always land in the right place.

New
Registered for a company

POST /v1/advisor with a referredCompanyId mints the advisor’s company-scoped ID.

Returning
Every sale after

That same advisorId is reused — consistent, correct commissioning.

Advisor onboarding

From sign-up to selling in minutes.

An advisor goes from registering on TravelJoy to a live Faye seller in one short setup — no back-and-forth.

Existing📝Step 1

Register

The advisor signs up through TravelJoy.

→
Existing🎬Step 2

Watch the training

A short Faye training video gets them ready.

→
New🏷️Step 3

Pick the company

Choose an agency from the /enhanced-partners list.

→
Existing🚀Live

Start selling

Quoting & selling on Faye, minutes later.

New company?

Agency not yet linked with Faye → it enters a pending state. TravelJoy and Faye review and approve the link, then the advisor goes live.

What it takes to switch

A small change for you. The lift is on us.

Nothing about your setup gets harder. You swap one field; Faye builds and runs everything behind it.

Your side

Register advisors, send their ID

Same endpoints you already use — one small change.

  • Register advisors via POST /v1/advisor — now optionally with a referredCompanyId, which mints the advisor's company-scoped ID.
  • Call GET /enhanced-partners to get your companies and the advisor IDs you created for each.
  • Send just the advisorId on quotes & purchases — no utm_source tags, no per-sale company field.
  • Move onto Faye's V2 endpoints — same concepts, a few request changes — and unlock 3 plans (First, Forward & Flagship).
Small effort · guided by Faye
Faye's side

Everything behind the scenes

The heavy lifting stays with us, so the change stays invisible to your advisors.

  • Build the ID resolver and the parent-company link.
  • Set up each agency's advisor mapping up front.
  • Move every agency across and check each sale matches.
  • Retire the old UTM path once everything lines up.
Main lift · owned by Faye
How we roll it out

In stages — nothing breaks.

These are live, paid policies, so we move in steps and prove every sale attributes exactly as it does today before switching anything off. Your current integration keeps working the whole way.

Phase 1
Faye

Build the company list

We stand up the agency list behind /enhanced-partners. Nothing changes on your side yet — today's flow runs untouched.

Phase 2
Together

Switch to IDs

You register advisors with a referredCompanyId and send just the advisorId on each sale. Tags and IDs can run side by side while you cut over at your own pace.

Phase 3
Faye

Move every agency across

We migrate all agencies onto the new model and shadow-check that each sale attributes and prices exactly as before — so no commission ever lands in the wrong place.

Phase 4
Faye

Retire the old path

Once every agency matches, we switch off the UTM matching. From then on, referrals run entirely on IDs — and UTMs are no longer needed.

While you're here

You move to V2 — and gain more to sell.

Moving to V2 puts you on Faye's current API version and opens up more products. A small lift with real upside — and it gets you ahead of V1's retirement. It's a separate track from the ID change: the two ship independently, in whichever order suits you.

Today · V1

One product, winding down

1 planretiring 01.01.2027
→
With you · V2

Three plans, actively built

First · Forward · Flagshipnew features ship here
🎚️

More to sell

Offer three plans — First, Forward & Flagship — instead of one, so travelers pick the coverage that fits.

🛡️

Future-proof

V2 is where new products and features land. Moving now means you grow with Faye instead of catching up later.

🪶

Small lift

Same concepts you already use — a few request changes. We guide the migration end to end.

🧭 The move, in four steps
  1. Point your calls at the V2 endpoints — /v2/quote, /v2/purchase, /v2/quote/multi.
  2. Handle the three plans — First, Forward & Flagship — the quote returns the options; show them, or pick one.
  3. Everything else carries over — advisor registration and the IDs work exactly as they do today.
  4. We run V2 and V1 side by side, so you migrate at your own pace with nothing turned off early.
A lightweight rollout
Step 1
Build in sandbox
Integrate V2 + the 3 plans in staging.
Step 2
Pilot
Run V2 for a few advisors, alongside V1.
Step 3
Roll out
Move the rest of your traffic to V2.
01.01.2027
V1 retires
Fully on V2, ahead of deprecation.
Heads up

V1 is planned for deprecation on 01.01.2027. Moving to V2 as part of this change means one migration, done ahead of time — on the version that keeps getting better.

A few things to align on

Open questions for the TravelJoy team.

Quick decisions that shape the smoothest rollout — none are blockers.

01Confirm the advisor + company shape in V2.Today you register each advisor up front via POST /v1/advisor (declaring their annual Faye training) and pass that advisorId on every quote and purchase. In V2 you'd keep doing exactly that and add the company ID per sale — does that fit how your platform stores the advisor-to-agency relationship?
02How will you use /enhanced-partners?Would you rather pull the full company list once and cache it, or look one up per sale? We can support either.
03Who approves a new agency?When an agency isn't linked with Faye yet, who signs off on your side — and what turnaround should advisors expect before they go live?
04How do you want to start?Pilot with one or two agencies first, or move everyone together? And is there a window that works best for the switch?
05Ship the two changes separately?The referral / ID move and the V2 + 3-products move are independent. We'd suggest running them as two separate tracks so neither blocks the other — which order do you prefer, and would you rather space them out or do them in one window?
06Migrate your direct advisors too?Some advisors sell directly under TravelJoy rather than on behalf of another agency. Do you want those moved onto the new model as well, or should we start with only the agency-referred advisors?
Agency gets its commission TravelJoy gets its cut Attribution created once, reused every time

Faye × TravelJoy · Enhanced Partners V2 · referral partnership overview