> ## 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 <Tooltip tip="A seed is a reference creator used as input for lookalike search.">seed</Tooltip> |
| `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 and a list of reasons:

```json theme={null}
{
  "data": [
    {
      "creator": {
        "id": "a3f1b9c2-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
        "name": "Nadia Kaur"
      },
      "match": {
        "score": 0.92,
        "reasons": [
          "Creates educational fitness content focused on home workouts",
          "High engagement rate suggests an active audience",
          "Consistent posting cadence fits the query intent"
        ]
      }
    }
  ]
}
```

Reasons typically cover:

* content relevance to the query
* audience quality signals
* posting consistency
* niche depth and focus

## 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 <Tooltip tip="Match decisions are AI-generated verdicts: good (strong fit), neutral (review manually), or avoid (weak fit).">decision</Tooltip> and supporting reasons:

```json theme={null}
{
  "data": [
    {
      "creator": {
        "id": "f9e8d7c6-b5a4-3f2e-1d0c-9b8a7f6e5d4c"
      },
      "match": {
        "score": 0.88,
        "decision": "good",
        "reasons": [
          {
            "text": "Strong fit — fitness content aligns with the protein bar category and audience skews health-conscious",
            "fact_id": "fact_abc123"
          }
        ]
      }
    }
  ]
}
```

| Decision  | Meaning                             |
| --------- | ----------------------------------- |
| `good`    | Strong fit for the campaign         |
| `neutral` | Could work — review manually        |
| `avoid`   | Weak fit, likely not worth pursuing |

Each reason may include an optional `fact_id` — an internal reference to the specific data point that supported it. This field has no user-facing purpose; you can safely ignore it.

## 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.