Docs / TEOScore / Score API

Score API

POST /v1/score/score takes flight options and returns, per option, a 0–100 TeoScore, its rank, the eight per-category scores, and a per-variable breakdown. (For a search that fetches and scores in one call, use the Search API.)

Request

POST /v1/score/score
Content-Type: application/json
Authorization: Bearer tfp_live_...

{
  "inputMode": "direct_options",
  "profileId": "usr_01HXY...",              // optional — applies the traveler's persona + preferences
  "options": [
    {
      "id": "opt_01HXY...",
      "currency": "USD",
      "cabinClass": "business",
      "totalPrice": 3200,                    // cash price
      "awardPrice": 57500,                   // points (for award options)
      "awardTaxesAndFees": 52,
      "details": { "flightLegs": [ /* … */ ] }
    }
  ],
  "context": { "searchType": "standard" },
  "searchPreferences": { "preferredArrivalTime": "20:00" }   // optional
}

Category weighting comes from the traveler's persona (resolved via profileId) — one of points_maximizer, executive, family_lead, luxe_enthusiast, digital_nomad, nervous_flier, weekend_warrior. With no profile, categories keep their default weights.

Response

{
  "scoredOptions": [
    {
      "optionId": "opt_01HXY...",
      "teoScore": 84,
      "rank": 1,
      "categoryScores": {
        "Financial Value & Loyalty": 92,
        "Schedule & Time Efficiency": 78,
        "Routing & Logistics": 81,
        "Risk & Protection": 90,
        "Ground Experience & Ancillaries": 70,
        "Cabin Comfort & Hardware": 85,
        "Seating Logistics & Strategy": 50,
        "Ground Connectivity": 50
      },
      "variables": { "V1": 88, "V2": 100, "V7": 100, "V16": 85 /* … */ },
      "explanation": "Score 84/100 — strongest in Cabin Comfort & Hardware (85)."
    }
  ]
}

categoryScores is keyed by the eight canonical TEO21 category labels. See the scoring engine for what each category and variable means — and which values are real vs estimated.

Versioning

Scoring follows the TEO21 spec (manifest 21.0.0): 8 categories, variables V1–V21. See scoring engine, onboarding, and go-live.

Request

POST /v1/score/score Content-Type: application/json Authorization: Bearer tfp_live_... { "inputMode": "direct_options", "profileId": "usr_01HXY...", // optional — applies the traveler's persona + preferences "options": [ { "id": "opt_01HXY...", "currency": "USD", "cabinClass": "business", "totalPrice": 3200, // cash price "awardPrice": 57500, // points (for award options) "awardTaxesAndFees": 52, "details": { "flightLegs": [ /* … */ ] } } ], "context": { "searchType": "standard" }, "searchPreferences": { "preferredArrivalTime": "20:00" } // optional }

Response

{ "scoredOptions": [ { "optionId": "opt_01HXY...", "teoScore": 84, "rank": 1, "categoryScores": { "Financial Value & Loyalty": 92, "Schedule & Time Efficiency": 78, "Routing & Logistics": 81, "Risk & Protection": 90, "Ground Experience & Ancillaries": 70, "Cabin Comfort & Hardware": 85, "Seating Logistics & Strategy": 50, "Ground Connectivity": 50 }, "variables": { "V1": 88, "V2": 100, "V7": 100, "V16": 85 /* … */ }, "explanation": "Score 84/100 — strongest in Cabin Comfort & Hardware (85)." } ] }

categoryScores is keyed by the eight canonical TEO21 category labels. See the scoring engine for what each category and variable means — and which values are real vs estimated.