> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Match Reasons
> Understand the AI explanations returned by search, lookalike, and match endpoints
# Match Reasons
Every scored result includes human-readable reasons explaining why a creator was returned. These reasons help you validate results, build trustworthy UIs, and debug queries that aren't landing.
## Where Reasons Appear
| Endpoint | Field | What it explains |
| ----------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/search` | `data[].match.reasons` | Why the creator matches your query |
| `POST /v1/creators/lookalike` | `data[].similarity.shared_traits` | Why the creator is similar to the seed |
| `POST /v1/creators/match` | `data[].match.reasons` | Why the creator is a good, neutral, or poor fit for the campaign |
## Search Reasons
Search results include a score, a plain-text `reasons` list, and — new — a structured `evidence` array that grounds each reason, plus a `confidence` value and a `low_confidence` marker:
```json theme={null}
{
"data": [
{
"creator": {
"id": "a3f1b9c2-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
"name": "Nadia Kaur"
},
"match": {
"score": 0.92,
"confidence": 0.92,
"low_confidence": false,
"reasons": [
"Publishes ingredient-education Reels on sensitive-skin routines",
"High engagement rate suggests an active audience"
],
"evidence": [
{
"text": "Publishes ingredient-education Reels on sensitive-skin routines",
"provenance": "post_evidence",
"fact_id": "b7c1f0a2-3d4e-5f60-8a9b-0c1d2e3f4a5b",
"source_post_id": "23256c2e-51fa-4389-a4a1-945e461e951b",
"evidence_quote": "Today we break down why fragrance wrecks a sensitive-skin barrier…"
},
{
"text": "High engagement rate suggests an active audience",
"provenance": "inferred",
"fact_id": null,
"source_post_id": null,
"evidence_quote": null
}
]
}
}
]
}
```
`reasons` (plain strings) is unchanged and still supported. `evidence` is the same reasons in a structured form — reach for it when you want to show a buyer *why* to trust a match, not just that it scored well.
### Provenance
Every entry in `evidence` carries a `provenance` label so you can tell a grounded claim from an inference. Strongest first:
| `provenance` | Meaning | What you get |
| --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `post_evidence` | Backed by a specific post you can open | `source_post_id` (fetch it via `GET /v1/posts/{id}`) and, when a genuinely supporting sentence exists, a verbatim `evidence_quote` from that post's caption or transcript |
| `profile_fact` | Backed by a stored profile fact, but with no clickable source post | `fact_id`, no `source_post_id` |
| `inferred` | Model reasoning over the profile, no direct post evidence | `text` only |
The `evidence_quote` is the sentence from the source post that best supports the reason, copied verbatim — never model-generated, so it can't be a fabricated citation. When no sentence in the post actually supports the claim, the quote is omitted (`null`) and you still get the clickable `source_post_id`. Treat `profile_fact` as weaker than `post_evidence` (there's nothing to click through to) and `inferred` as the softest signal — style them accordingly.
### Confidence and the weak tail
`confidence` mirrors `score` (0–1). `low_confidence` is `true` when a result falls in the weak tail of the ranking — a non-breaking marker so you can draw a "weaker matches" divider instead of presenting every returned creator as an equally strong match. It never changes which results are returned; it only labels them.
## Lookalike Reasons
Lookalike results explain shared traits between the seed creator and the match:
```json theme={null}
{
"data": [
{
"creator": {
"id": "e8d7c6b5-a4f3-2e1d-0c9b-8a7f6e5d4c3b",
"name": "Marcus Rivera"
},
"similarity": {
"score": 0.87,
"shared_traits": [
"Both focus on fitness and wellness content",
"Similar audience demographics",
"Comparable engagement patterns on workout videos"
]
}
}
]
}
```
Typical themes: content overlap, audience similarity, style, and performance patterns.
## Campaign Match Reasons
`POST /v1/creators/match` returns structured campaign-fit output with a decision and supporting reasons:
```json theme={null}
{
"data": [
{
"creator": {
"id": "f9e8d7c6-b5a4-3f2e-1d0c-9b8a7f6e5d4c"
},
"match": {
"score": 0.88,
"decision": "good",
"reasons": [
{
"text": "Reviews protein bars and macro-friendly snacks in weekly Reels",
"provenance": "post_evidence",
"fact_id": "fact_abc123",
"source_post_id": "9b8a7f6e-5d4c-3b2a-1f0e-9d8c7b6a5f4e",
"evidence_quote": "This bar packs 20g of protein and actually tastes like dessert…"
}
]
}
}
]
}
```
| Decision | Meaning |
| --------- | ----------------------------------- |
| `good` | Strong fit for the campaign |
| `neutral` | Could work — review manually |
| `avoid` | Weak fit, likely not worth pursuing |
Campaign-match reasons carry the same `provenance` label as search evidence (`post_evidence`, `profile_fact`, `inferred`). When present, `source_post_id` points at a post you can open via `GET /v1/posts/{id}`, and `evidence_quote` is a verbatim snippet from that post. The `fact_id` is an internal reference to the supporting data point — use `source_post_id` and `evidence_quote` for anything user-facing.
## How to Use Reasons
* **Surface them in your UI.** Reasons make AI-driven results feel transparent. Showing "Strong sustainable fashion focus" next to a creator helps your users trust the ranking.
* **Validate your queries.** If the reasons don't match your intent, the query needs refining — tighten the language or add filters.
* **Compare across results.** Reasons help you understand why one creator ranked higher than another, beyond just the numeric score.
* **Debug broad searches.** When results feel off, the reasons usually reveal whether the query was too vague or the filters too loose.
## Scores vs Reasons
Treat the score as the summary and the reasons as the explanation. A high score with reasons that don't match your intent is a signal to refine the query, not to trust the number.