# User trust scores

A yes/no fraud flag tells you who to stop. A **trust score** tells you how far
to let everyone else go: who can list without review, whose payouts clear
instantly, who needs to verify first. SigWise keeps a score for every user,
updated as they act, on a scale whose levels you describe in words.

## Define the score

A `score` signal places each user on an ordered list of levels. The answer is
a number from `0` (the first level) to `levels − 1` (the last), with fractions
in between, plus a `confidence`.

```json
PUT /v1/signals/trust_score
{
  "type": "score",
  "instructions": "How much can other users and the platform trust this user?",
  "criteria": [
    "high risk: deceptive, abusive or clearly fraudulent",
    "unproven: new or thin history, nothing wrong yet",
    "neutral: normal activity, minor issues",
    "trusted: long, consistent, positive history"
  ]
}
```

Every new account already has a three-level `trust_score`; replace its levels
with ones that match the decisions you make.

## Feed it evidence

Trust is built from behaviour over time, so send the events a human reviewer
would weigh:

```json
POST /v1/objects/user-42/events
{
  "object_type": "user",
  "events": [
    { "type": "event", "name": "order.completed", "metadata": { "amount": 120, "rating": 5 } },
    { "type": "event", "name": "report.received", "metadata": { "reason": "no-show", "reporter_trust": "trusted" } },
    { "type": "message", "content": "Sorry, I was sick, can we reschedule for tomorrow?" }
  ]
}
```

Each analysis sees the user's recent events plus a rolling summary of
everything before, so one bad day does not erase a long good record, and a
long record does not hide a sudden change.

## Read and use it

```json
GET /v1/objects/user-42
{
  "object_id": "user-42",
  "analysis": [
    { "key": "trust_score", "type": "score", "score": 2.4, "confidence": 0.8 }
  ]
}
```

- **Gate actions in your code.** Instant payouts above `2.5`, manual review
  below `1`.
- **Rank users.** `GET /v1/objects?sort=trust` lists the most trusted first.
- **Find who to review.** `GET /v1/objects?q=trust_score < 1`. See
  [Search and conditions](https://sigwise.ai/docs/guides/queries.md).
- **Get told when trust drops.** A [rule](https://sigwise.ai/docs/guides/rules.md) with
  `"when": "trust_score < 1"` fires once when a user falls below the line.

## Combine with other signals

Conditions can combine signals, such as
`is_scammer >= 60 and trust_score < 1`, so an alert only fires when a
suspicious message comes from someone without a track record.

## Next steps

- [Marketplace scam detection](https://sigwise.ai/docs/use-cases/marketplace-scam-detection.md)
- [Signals](https://sigwise.ai/docs/guide/signals.md): the three signal types and how to write criteria.