> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Ban Insurance > If a Pro number is banned and the ban is attributed to Polymorfa, the credits that number consumed in the 30 days before the ban are returned to your balance. If a Pro number is banned and the ban is attributed to Polymorfa, the credits that number consumed in the 30 days before the ban are returned to your balance. That sentence is the whole promise. This page says who it covers, how the amount is worked out, what Polymorfa looks at before deciding, and what you see at each step. ## Who it covers Ban Insurance is included on **Pro** numbers. Free and Standard numbers get health, findings, restrictions, and the rest of BanSafe, but no claim. Coverage uses the number's plan when the ban occurred, including for a late report. Moving the number to another plan after the ban does not change the plan used for its claim. Incidents from before Polymorfa began recording plan history do not open automatic claims because their coverage cannot be verified. Claims already filed keep the coverage recorded on them. ## A claim is filed for you You never file a claim. When a ban is recorded on a covered number — either because Polymorfa saw WhatsApp apply it, or because you [reported it](/guides/bansafe/overview#reporting-a-ban-yourself) — a claim opens against that incident by itself. If you report a ban that Polymorfa also records, both incidents can have claims. They share the same refund limit; the same usage is never refunded twice. A claim then moves through these states: | Status | What it means | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `filed` | The claim is open and waiting for review. | | `under_review` | Someone at Polymorfa is looking at it. | | `approved` | The claim was accepted. A positive amount is awaiting payment; a zero amount means review and refund limits left no credits to return. | | `denied` | The claim was reviewed and not accepted. | | `paid` | The credits are on your balance. | | `reversed` | What Polymorfa knew about the ban changed after the refund, and the credits were taken back. | Credits move only when a person approves the claim. Nothing is credited automatically. ## How much comes back Three numbers, and the smallest one wins: * **What the number used.** The credits that number consumed in the 30 days ending at the moment the ban started — not at the moment the claim was filed, so reporting a ban late never enlarges a refund. * **What the plan returns.** 30 days at the number's own daily rate. * **What is left.** A ban on a number that was already refunded inside the same 30-day window returns only what the first refund did not, because the credits were consumed once. Across an organization, refunds in any rolling 90 days never exceed what that organization bought in the same period. Approved refunds count toward those limits while payment is pending. Retrying a payment keeps its approved amount and does not create a second refund. Taking back an earlier refund does not count as new usage. Your claim shows its measured usage, plan cap, and refund amount. The amount is checked again at approval against earlier refunds and pending approvals. Credits consumed before Polymorfa began attributing usage to individual numbers are not counted, because they cannot be shown to have come from this number. A claim covering that period reports what it can measure and says so. ## What the ban is attributed to Before a claim is reviewed, Polymorfa works out what the ban points at, from what it measured in the same 30 days. The answer is on the claim as `verdict`, with a sentence explaining it. | Verdict | What it means | Effect | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `other_device` | Another device linked to the number was sending on days when Polymorfa sent nothing, at a volume and pace WhatsApp restricts numbers for. | Not refunded | | `customer_conduct` | Polymorfa was already restricting the number's own sending, or named the same serious problem for a week, before the ban. | Not refunded | | `shared_network` | The number reached WhatsApp from a connection shared with numbers that were being restricted. Polymorfa chose that connection. | Refunded | | `ours` | Nothing in the 30 days points at how the number was used, and no other device on the account was sending. | Refunded | | `inconclusive` | Polymorfa could not see enough of the 30 days to say. | A person decides | The verdict is a recommendation, not the decision. A person reviews every claim. The review includes restrictions that overlapped the 30-day window, even if they started earlier or were lifted before the review. Withdrawing a report stops new claims from opening against it. It does not remove an independently recorded WhatsApp incident. ## Evidence from other linked devices Deciding whether another device on your account caused a ban means measuring your other linked devices — the phone the number is paired to, other browsers, other tools. That is a different question from measuring the messages Polymorfa sent, so it is a separate choice you make per project, and it is off until you turn it on. With it off, a claim is still filed and still reviewed, but Polymorfa cannot rule another device in or out, so the verdict is `inconclusive` and a person decides. ### What is measured With it on, Polymorfa keeps counts, per device and per hour: * how many messages the device sent, and to how many people; * how many of those went to people who had never written to the number first; * the most it sent in any 60 seconds, and in any 5 minutes; * the hours of the day it sent in, and the gaps between its messages; * how much it sent in hours when Polymorfa itself sent nothing; * what class of device it is, from a fixed list: phone, desktop app, browser, WhatsApp Business API, or unknown. Nothing else. Polymorfa never records a message, a recipient, a phone number, a device model, or a device name from another device, and none of it reaches the health score or your safety findings — it is used to decide a claim and for nothing else. Evidence is kept for as long as the safety measurements it arrives with, and a claim reports how much of the 30 days it actually covers. Below half the window, the verdict is `inconclusive` whatever the counts say: an unmeasured stretch is never read as a quiet one. If a report reaches its collection limits, device evidence for that hour is unavailable. Polymorfa counts the hour as unmeasured. Missing evidence never proves that no other device sent, so it cannot support a confident attribution on its own. Turning evidence collection off deletes the stored device measurements for the project and stops them from being used for new claims. Existing claims keep the evidence summary recorded when they were filed. ### Turn it on ```bash theme={null} curl -X PUT https://api.polymorfa.com/platform/projects/$PROJECT_ID/insurance-evidence \ -H "Authorization: Bearer $POLYMORFA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' ``` ```json theme={null} { "projectId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f01", "enabled": true, "banInsuranceIncluded": true } ``` `banInsuranceIncluded` says whether a ban on a number in this project is covered by Ban Insurance today. It does not gate the setting: turn evidence on before you move a number to Pro and the evidence is already there for a ban after the upgrade. Send `{"enabled": false}` to stop. Collection stops on every connected number at once, and what was already collected on those numbers is discarded. Reading the setting is `GET` on the same path. Changing it needs `sessions:manage`, or organization owner, admin, or developer if you are signed in to Console. ## What you see Console shows a **Ban Insurance** section on the [Safety page](/console/safety#ban-insurance), beside what WhatsApp did to the number: the state of each claim, what the ban was attributed to, and all three amounts. When credits are returned, everyone on the team who has the notification turned on gets it in Console and by email. It arrives as a billing notice, because the credits land on the balance. ## Read a claim ```bash theme={null} curl https://api.polymorfa.com/platform/bansafe/claims \ -H "Authorization: Bearer $POLYMORFA_API_KEY" ``` Filter with `projectId`, `session`, and `status`, and page with `cursor` and `limit`. One claim by id is `GET /platform/bansafe/claims/{claimId}`. ```json theme={null} { "id": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f22", "incidentId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11", "session": "sales-1", "phoneNumber": "+15551234567", "status": "paid", "verdict": "ours", "windowStart": "2026-08-07T14:03:12.000Z", "windowEnd": "2026-09-06T14:03:12.000Z", "measuredCents": 1080, "capCents": 1080, "amountCents": 1080, "evidence": { "attributionRuleVersion": 1, "windowDays": 30, "deviceEvidence": true, "otherDevices": 0, "restrictedInWindow": false, "criticalFindingDays": 0, "sharedConnection": false, "measuredHours": 698 }, "summary": "The credits this number used in the 30 days before the ban are back on your balance.", "reason": "Nothing in the 30 days before the ban points at the way this number was being used, and no other device on the account was sending. The ban is ours.", "decidedAt": "2026-09-07T09:12:00.000Z", "paidAt": "2026-09-07T09:12:00.000Z", "createdAt": "2026-09-06T14:10:00.000Z" } ``` Amounts are integer cents of credits: 1 credit = 1 cent. `evidence.attributionRuleVersion` identifies the attribution rules used when the claim was filed. It is `null` on claims filed before rule versioning was recorded. The claim keeps that version, its verdict, and its evidence summary when project settings or retained measurements change later. ## Follow a claim from your own system Subscribe to `bansafe.claim`. It fires when the claim is filed and again on every state it reaches, carrying the incident id, the three amounts, the verdict and the two sentences. See [BanSafe events](/api/webhooks#bansafe-events). ## Related * [BanSafe overview](/guides/bansafe/overview) * [Safety limits](/guides/bansafe/enforcement) * [Safety in Console](/console/safety)