Match Evaluation

Score the compatibility between two users on a 0.0–1.0 confidence scale and explain why with a category and a one-sentence rationale.

POST /v1/match/evaluate

Request

{
  "user_a": {
    "id": "usr_a",
    "photos": ["https://…/a1.jpg"],
    "bio": "…",
    "preferences": { "interests": ["…"], "lifestyle": ["…"] }
  },
  "user_b": {
    "id": "usr_b",
    "photos": ["https://…/b1.jpg"],
    "bio": "…",
    "preferences": { "interests": ["…"], "lifestyle": ["…"] }
  }
}

If you've already called Preference Inference for both users, pass the resulting preferences block here — it improves match quality and roughly halves latency.

Response

{
  "request_id": "req_01H…",
  "confidence": 0.82,
  "reason_category": "shared_hobbies",
  "reason": "Both spend weekends outdoors; she runs trails, he climbs — same crowd, same energy."
}

Field	Type	Notes
confidence	number	0.0 – 1.0. Treat ≥ 0.7 as a high-quality match.
reason_category	enum	One of: shared_hobbies, lifestyle_fit, similar_goals, complementary_traits, aesthetic_alignment
reason	string	Natural-language one-liner safe to show end-users

Latency

P50 ~ 600 ms, P95 ~ 1.2 s. Designed for real-time use in feed scoring.

Use it for

• Pre-scoring the next page of profile cards in a discovery feed
• Re-ranking candidates by reason category (e.g., show "lifestyle_fit" matches first to a user known to value lifestyle compatibility)
• Powering "why did we surface this?" UI affordances

Common errors

Code	Why
invalid_user	Either user object missing required fields
unsafe_content	One of the photos failed our content safety filter
quota_exceeded	Free tier monthly cap reached — see Pricing