> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reputation Remediation

> Submit spam-flagged phone numbers for re-evaluation, then poll the request to track per-number remediation results.

## Overview

When one of your monitored numbers is flagged with an elevated `spam_risk`, you can submit it for **reputation remediation** - a request to the call-analytics networks to re-evaluate the number's classification. You submit a batch of numbers, Telnyx forwards the request on your behalf, and you poll the request to track its status and per-number outcome.

Remediation is **asynchronous**. The submit call returns `202 Accepted` with a request id; the request then moves through processing states until it completes. Use the GET endpoints to poll status and per-number results.

<Warning>
  Submitting a remediation request does **not** guarantee a number will be
  removed from any spam or block list. Remediation is a **re-evaluation
  request** to the call-analytics networks - the outcome may be that the number
  remains flagged (`requires_review` or `refused`).
</Warning>

<Warning>
  Even after a number is successfully remediated, calls from it can **still be
  blocked or labeled** by downstream spam filters and carriers. Those systems
  are outside Telnyx's control, and a successful remediation does not override
  them.
</Warning>

<Note>
  Both Number Reputation approval gates must be cleared (reputation `status`
  **and** `loa_status` both `approved`) and the Number Reputation Terms of
  Service accepted before you can submit remediation requests. See the
  [LOA guide](/docs/branded-calling/number-reputation/loa) and
  [Reputation Settings](/docs/branded-calling/number-reputation/settings).
</Note>

## Submit numbers for remediation

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"],
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation"
  }'
```

| Field           | Required | Description                                                                                        |
| :-------------- | :------- | :------------------------------------------------------------------------------------------------- |
| `phone_numbers` | yes      | Phone numbers in E.164 format. **1 to 2,000** per request. Must belong to this enterprise.         |
| `call_purpose`  | yes      | Free-text description of how the numbers are used (1 to 2,000 chars).                              |
| `contact_email` | no       | A contact email for this remediation request, used for tracking and any follow-up (max 255 chars). |
| `webhook_url`   | no       | Optional `https://` URL to receive status notifications (max 2,048 chars).                         |

The endpoint returns **`202 Accepted`** with the persisted request and its initial `status` of `pending`:

```json theme={null}
{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "pending",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T18:06:51.940749Z",
    "tier1_completed_at": null,
    "tier2_completed_at": null,
    "results": null
  }
}
```

<Note>
  A number that already has an in-flight remediation request cannot be submitted
  again - the request returns **`409 Conflict`**. Numbers that do not belong to
  this enterprise return **`422 Unprocessable Entity`**.
</Note>

### Count fields

| Field                      | Meaning                                                                                                               |
| :------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `phone_numbers_count`      | Total numbers in the batch, including any later cancelled. May exceed the sum of the per-category result buckets.     |
| `phone_numbers_submitted`  | Numbers accepted for remediation (not rejected as ineligible). Counts numbers still queued as well as processed ones. |
| `phone_numbers_ineligible` | Numbers rejected before submission (for example, in a cooldown window).                                               |

## Get a remediation request

Retrieve full detail for one request, including per-number results once they are available:

```bash theme={null}
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation/9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A completed request includes the populated `results` object:

```json theme={null}
{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "completed",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T19:42:10.112233Z",
    "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
    "tier2_completed_at": "2026-06-07T19:42:10.000000Z",
    "results": {
      "remediated": ["+12025551234"],
      "not_flagged": [],
      "requires_review": ["+12025555678"],
      "ineligible": [],
      "refused": []
    }
  }
}
```

A request that is not found - or does not belong to this enterprise - returns **`404 Not Found`**.

### Status values

`status` is the customer-facing meta-status:

| `status`      | Meaning                                                        |
| :------------ | :------------------------------------------------------------- |
| `pending`     | Request accepted and queued; not yet forwarded for review.     |
| `in_progress` | Forwarded and under review by the call-analytics networks.     |
| `completed`   | Review finished. Inspect `results` for the per-number outcome. |
| `failed`      | The request could not be processed.                            |
| `cancelled`   | The request was cancelled.                                     |

`results` is `null` while the request is still pending and is populated once results are available.

### Per-number result buckets

When `results` is populated, each number falls into exactly one bucket. Empty buckets are returned as empty arrays (never omitted), so you can iterate without null-checking each key:

| Bucket            | Meaning                                                                        |
| :---------------- | :----------------------------------------------------------------------------- |
| `remediated`      | The number's classification was successfully re-evaluated and cleared.         |
| `not_flagged`     | The number was not flagged, so no remediation was needed.                      |
| `requires_review` | The number needs further review and remains flagged for now.                   |
| `ineligible`      | The number was rejected before submission (for example, in a cooldown window). |
| `refused`         | The re-evaluation request was declined; the number remains flagged.            |

<Warning>
  A number landing in the `remediated` bucket means the analytics networks
  re-evaluated and cleared it - it does **not** guarantee the number is removed
  from every spam list, and downstream carriers and spam filters may still
  block or label calls from it.
</Warning>

## List remediation requests

```bash theme={null}
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?page[number]=1&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

List items are a **slim shape** - they omit `results`, `webhook_url`, and the count breakdown. Call [get by id](#get-a-remediation-request) for full detail.

```json theme={null}
{
  "data": [
    {
      "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
      "status": "completed",
      "phone_numbers_count": 2,
      "call_purpose": "Outbound appointment reminders for our dental clinic.",
      "created_at": "2026-06-07T18:06:51.940749Z",
      "updated_at": "2026-06-07T19:42:10.112233Z",
      "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
      "tier2_completed_at": "2026-06-07T19:42:10.000000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_results": 1,
    "total_pages": 1
  }
}
```

### Pagination

Pagination is JSON:API. Page numbering is **1-based**; `page[size]` **defaults to 20** and is capped at **250**.

```bash theme={null}
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?page[number]=2&page[size]=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filters

| Filter                    | Description                                                                                        |
| :------------------------ | :------------------------------------------------------------------------------------------------- |
| `filter[status]`          | Filter by customer-facing status: `pending`, `in_progress`, `completed`, `failed`, or `cancelled`. |
| `filter[created_at][gte]` | Created on or after this ISO 8601 timestamp.                                                       |
| `filter[created_at][lte]` | Created on or before this ISO 8601 timestamp.                                                      |

```bash theme={null}
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?filter[status]=completed&filter[created_at][gte]=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Next steps

* [Query reputation scores](/docs/branded-calling/number-reputation/phone-numbers) to see which numbers are flagged.
* [Reputation Settings](/docs/branded-calling/number-reputation/settings) to manage auto-refresh schedules and the activation lifecycle.