---
title: Phone Reputation | API Docs
description: How we measure reputation of a phone line and how to check it before you send.
---

Note

This feature is currently in beta and may be inaccurate at times. We are actively improving our reputation models. Expect additional engagement and activity signals as the scoring gets smarter.

Caution

The field is now called `reputation`. `health_status` is a **deprecated** alias that returns the same value and will be removed — migrate to `reputation`.

Every phone line carries a `reputation` — a line-level read on whether the line as a whole is in good standing. It’s the line-wide companion to [chat health](/guides/chats/chat-health/index.md), but it is **not** simply a sum of it.

Phone reputation draws on two kinds of signals:

- **Patterns across the conversations on the line** — engagement and deliverability across the line’s chats, in aggregate. This is the larger driver, and it’s closely related to [chat health](/guides/chats/chat-health/index.md).
- **Line-level activity that no single conversation reveals** — how many different recipients the line messages in a short window, how many brand-new conversations it starts in a day, and its overall send pace.

You’ll see `reputation` on each number returned by [`GET /v3/phone_numbers`](/api/resources/phone_numbers/methods/list/index.md). It’s a prediction of where the line is heading — treat it as a pre-send gate, not a report.

## How to use it

- **[`GET /v3/phone_numbers`](/api/resources/phone_numbers/methods/list/index.md)** — every line in the list response carries its current `reputation`.
- **[`phone_number.status_updated`](/guides/webhooks/events#phone-number-events/index.md) webhook** — fires when `reputation` changes. The payload carries `previous_reputation` and `new_reputation` (and the deprecated `previous_health_status` / `new_health_status` aliases), so you can react the moment a line moves to `AT_RISK` or `CRITICAL`.

Check `reputation` shape and value before you queue outbound messages for a line — the same pre-send gate pattern as chat health, one level up. Use it to route work toward your healthiest lines: if a line is `CRITICAL`, onboard new recipients onto a `HEALTHY` line instead and let the `CRITICAL` one recover before you send more on it.

```
const { phone_numbers } = await client.phoneNumbers.list();


for (const pn of phone_numbers) {
  switch (pn.reputation.status) {
    case 'HEALTHY':  break;                 // send normally, safe to onboard new recipients
    case 'AT_RISK':  reviewLine(pn); break; // slow the pace, check chat health
    case 'CRITICAL': pauseLine(pn); break;  // stop outbound, route new recipients elsewhere
  }
}
```

Acting on the status before each send is what turns the signal into delivery improvement — ultimately leading to a healthier line.

## Statuses

| status                  | What it means                                                    | What to do                                                                  |
| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`HEALTHY`](#healthy)   | The line is in good standing.                                    | Send normally.                                                              |
| [`AT_RISK`](#at-risk)   | The line’s overall engagement is trending down.                  | Slow the line’s send pace and use chat health to find conversations to fix. |
| [`CRITICAL`](#critical) | Strong signals that messages from this line aren’t landing well. | Pause outbound on the line until it recovers.                               |

### HEALTHY

The line looks like it’s operating normally. Engagement and deliverability across its conversations look good, and its overall activity is within a normal range. No action needed.

### []()AT\_RISK

One or more soft signals suggest the line as a whole is heading in the wrong direction. Common drivers fall into two groups:

- **Conversation patterns.** Engagement is low across many of the line’s chats. [Chat health](/guides/chats/chat-health/index.md) is the best place to see this per-conversation.
- **Line-level activity.** The line is reaching a large number of different recipients in a short window, starting many brand-new conversations in a single day, or its overall send volume spiked — patterns that look risky at the line level even when individual chats are fine.

`AT_RISK` is a *warning*, not a hard stop. Recommended playbook:

1. **Check chat health.** Pull [chat health](/guides/chats/chat-health/index.md) for the line’s conversations to find the `AT_RISK` and `CRITICAL` chats, and fix those first.
2. **Slow the line’s overall pace.** Reduce total send volume until signals recover.
3. **Bias outbound toward messages that elicit replies.** Questions and follow-ups outperform broadcasts.
4. **Spread activity out.** Avoid contacting many new recipients or opening many new conversations in a single burst.
5. **Vary your content.** Repeated near-identical messages across the line amplify the signal.

Watch for the line moving back to `HEALTHY` (good) or down to `CRITICAL` (act fast).

### CRITICAL

Strong signals that messages from this line aren’t reaching recipients the way you expect. Continuing to send is unlikely to help and may make the situation worse.

Recommended action: pause outbound on the line. Re-engage only after it returns to `HEALTHY`.

## Scenarios

| Scenario                                                         | Likely status           |
| ---------------------------------------------------------------- | ----------------------- |
| Send volume with engaging reply rates from users                 | `HEALTHY`               |
| Rapid increase in new conversations with little to no engagement | `AT_RISK` or `CRITICAL` |
| Many of the line’s chats are `AT_RISK` or `CRITICAL`             | `AT_RISK` or `CRITICAL` |

## Phone reputation and chat health

Chat health and phone reputation are related but answer different questions:

- **[Chat health](/guides/chats/chat-health/index.md)** scores a single conversation — is *this* recipient engaging, are messages landing.
- **Phone reputation** scores the line — both the aggregate of its conversations *and* line-level activity that no single conversation reveals, like how broadly and how fast the line is messaging.

## Tips

- New lines start as `HEALTHY` and move to `AT_RISK` or `CRITICAL` as signals warrant.

## FAQ

**Does phone reputation read message content or store any PII?**

No. Phone reputation scoring runs on anonymous, aggregate signals — line-level volume, send/receive ratios, recipient counts, conversation pace, and similar metadata. Linq does not collect or store message content or other PII to compute `reputation` for phone numbers.

**Why is there no `OPTED_OUT` on phone reputation?**

Unlike chat health, phone reputation has **no `OPTED_OUT` status**. Opt-out is a per-recipient signal scoped to a single conversation — it can’t apply to a whole line. You’ll only ever see `OPTED_OUT` on [chat health](/guides/chats/chat-health#opted-out/index.md).

**Why are most of my high-volume lines `AT_RISK`?**

Volume alone shouldn’t cause this. Check whether user reply rates dropped on those lines as they scaled — phone reputation weighs engagement relative to volume, not necessarily volume on its own; although, too many new chats sent at once within a short period can cause `AT_RISK` signals.

**Is `AT_RISK` reversible?**

Yes. The status reflects recent behavior. Improving send pace and engagement on the line returns it to `HEALTHY` as new signals come in.

**Should I migrate users off an `AT_RISK` line?**

No — fix the line. Migrating users off carries the same underlying sending pattern to a new line and spreads the issue rather than solving it. Use [chat health](/guides/chats/chat-health/index.md) to find the conversations dragging the line down, address those, and let the line recover.

## Related

- [Phone Numbers](/guides/phone-numbers/index.md) — discover and monitor your lines
- [Chat Health](/guides/chats/chat-health/index.md) — per-conversation health scoring
- [API Reference: List Phone Numbers](/api/resources/phone_numbers/methods/list/index.md)