# Set a Health rule and handle restrictions

> Stop, slow or log out a Number when its Health drops, report a ban, and tell your own actions apart from WhatsApp's.

A Health rule acts on a Number when its Health falls below a score you choose.
This page shows how to set one, how to read what it did, and how to handle a
restriction from Polymorfa or from WhatsApp.

Polymorfa keeps three facts apart, and so should your integration:

| Fact | Where you read it |
| --- | --- |
| Health, an estimate of the Number's state | [Health](https://docs.polymorfa.com/safety/health) |
| An action your project rule or Polymorfa applied | Health rule activity, `GET /platform/bansafe/enforcement` |
| A restriction observed from WhatsApp | `bansafe.incident`, the Number's incident history |

Low or unknown Health does not prove that WhatsApp restricted a Number.

## Before you begin

- In the Console, you need the owner or admin role on the team to change a
  rule. Members can read it.
- Through the API, use a team key or project token with `sessions:manage` to
  change a rule and `sessions:read` to read it.
- To send the webhook, the project needs an enabled, project-wide native
  webhook subscribed to `bansafe.health_threshold` or to all events. See
  [Webhooks](https://docs.polymorfa.com/development/webhooks).

## Set a Health rule

Each project has one rule. It is off until you enable and save it. The rule
acts only on a fresh, available estimate below the threshold: a score equal to
the threshold, unknown Health and stale evidence trigger nothing.

| Action | API value | What happens |
| --- | --- | --- |
| Notifications only | `none` | The Number keeps running. Polymorfa sends the notifications you chose. |
| Stop the number | `stop` | The Number disconnects and keeps its linked credentials, so you can start it again. |
| Slow down sending | `slow_down` | Outbound sending is capped at the messages-per-second value you set. |
| Log out | `log_out` | The Number is unlinked. Pair it again before it reconnects. |

Email and webhook notifications can accompany any action. An enabled rule
needs an action or at least one notification.

**Console:**

1. Open the project's **Safety** page and select **Settings**.
2. Under **Health rule**, turn the rule on and move the slider to the
   threshold, a Health value from 0 to 100.
3. Choose an action. For **Slow down sending**, enter the messages per second.
4. Select email, webhook or both. The webhook option stays disabled until the
   project has a matching webhook.
5. Select **Save Health rule**.

If someone saved a newer version first, the Console keeps your edits and asks
you to reload the saved rule before trying again.

**API:**

Read the rule to get its `version`, then replace it with that version:

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/$PROJECT_ID/health-policy" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3,
    "enabled": true,
    "threshold": 40,
    "sessionAction": "slow_down",
    "slowDownMps": 1,
    "emailNotification": true,
    "webhookNotification": false
  }'
```

Every field is required. A `version` that no longer matches the stored rule is
refused, so read again and retry with the new version. See
[Update the Health policy](https://docs.polymorfa.com/api/bansafe/update-project-health-policy-settings).

Saving a rule does not act on any Number at that moment. It governs the next
Health evaluations.

### Pacing rates

`slowDownMps` must be greater than zero and no higher than the project's
sending limit: the lowest throughput among the project's default Number tier
and the tiers of its Numbers (5, 10 or 100 messages per second for Free,
Standard and Pro). The Console and the API refuse a higher value rather than
lowering it for you.

## Check what the rule did

**Console:**

Open the **Activity** tab on the **Safety** page. Each row of **Health rule
activity** shows the Number, the action, its status or outcome, the Health and threshold
that triggered it, the estimator and the completion time. The history stays
after a rule stops or logs out a Number.

**API:**

```bash
curl "https://api.polymorfa.com/platform/bansafe/health-actions?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"
```

Filter by `session` or `status`. Results are newest first and use cursor
pagination. See [List Health actions](https://docs.polymorfa.com/api/bansafe/list-ban-safe-health-actions).

An outcome is one of `applied`, `cleared`, `notification_queued`,
`superseded`, `expired`, `not_applied` or `delivery_failed`. Polymorfa checks
the latest Health again before it applies a queued action.

## Polymorfa restrictions

Polymorfa can also limit a Number's sending. The Console shows a banner above
the Number's findings that names the limit and what remains before it lifts,
for example: *"This lifts after 48 hourly safety checks meet the restriction's
recovery threshold. 12 of 48 done, and 2 findings must resolve first."*

Read restrictions with `GET /platform/bansafe/enforcement`. `state: "applying"`
means the restriction is stored and the connected Number has not confirmed
it yet; Polymorfa keeps delivering it. A restriction stays in force until it is
lifted. See [List enforcement](https://docs.polymorfa.com/api/bansafe/list-ban-safe-enforcement).

### Appeal a restriction

1. Acknowledge every open finding on the Number. See
   [Acknowledge a finding](https://docs.polymorfa.com/safety/findings#acknowledge-a-finding).
2. Open the Number on the **Safety** page and, under **Findings**, select
   **Appeal this restriction**.

Appeals are available in the Console to team owners and admins. Filing an
appeal does not lift the restriction, and neither does acknowledging a
finding. Health changes after new evidence; a restriction lifts when its
recovery conditions are met.

## WhatsApp restrictions

`bansafe.incident` reports a restriction observed from WhatsApp, or one your
team reported, when it is recorded and again when it settles. It does not mean
Polymorfa applied an action. A stopped or slowed Number keeps its own observed
account state, shown with its timestamp and source.

`session.restriction_updated` reports one WhatsApp restriction as it starts
and ends: the limit on starting conversations and calls with people the Number
has not chatted with. While it is active, Polymorfa refuses calls to those
people with [`number_restricted`](https://docs.polymorfa.com/api/errors#number-restricted). See
[Calls](https://docs.polymorfa.com/calls).

With a team key, list the team's recorded bans with `GET /platform/bans` and
the bans in force with `GET /platform/bans/active`.

## Report a ban

When WhatsApp bans or restricts a Number and Polymorfa did not observe it,
report it so it is kept with the Number's history. A report becomes an
observed incident. It does not set or replace Health. On a Pro Number, it also
opens a [Ban Credit](https://docs.polymorfa.com/safety/ban-insurance) claim.

**Console:**

1. Open the Number on the **Safety** page.
2. Select **Report a ban** at the top of the Number's view.
3. Enter the date it happened and an optional note, then confirm.

**API:**

```bash
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Idempotency-Key: ban-report-sales-1" \
  -H "Content-Type: application/json" \
  -d '{ "session": "sales-1", "occurredAt": "2026-09-06T09:00:00Z", "note": "Number banned during outreach" }'
```

`session` is required; `note` accepts up to 500 characters. Retrying with the
same `Idempotency-Key` for the same Number returns the original report with
`created: false`. Reusing the key for another Number returns
`409 bansafe_incident_idempotency_scope_conflict`.

Read reported and observed incidents with `GET /platform/bansafe/incidents`.
To withdraw your own report, call
`POST /platform/bansafe/incidents/{incidentId}/retract` with a team key. An
incident observed from WhatsApp cannot be withdrawn and returns
`409 bansafe_incident_not_a_report`.

## See also

- [Read a Number's Health](https://docs.polymorfa.com/safety/health)
- [Review recorded findings](https://docs.polymorfa.com/safety/findings)
- [Safety in the Console](https://docs.polymorfa.com/safety/console)
- [BanSafe events](https://docs.polymorfa.com/api/events#safety-events)
