Integrating Number Reputation Management (NRM) into Your Platform

---

Overview

Number Reputation Management (NRM) lets you monitor whether your customers' outbound phone numbers have been labeled as spam, scam, or telemarketer by the major US carriers — and automatically trigger remediation when a label is detected.

This guide walks you through integrating Bandwidth's NRM APIs into your platform so your customers can monitor and manage the reputation of their numbers.

How It Works

---

Prerequisites

Before you can use the NRM APIs:

1. Your organization's account is NRM-enabled. Bandwidth provisions this after you and your organization complete the registration and approval process. Contact your Bandwidth account team to begin onboarding if you haven't already.

2. Your end-customers are registered. Each customer whose numbers you want to monitor must complete a separate approval process (via Bandwidth). Once approved, Bandwidth creates a Customer record in NRM that you can reference in the API. You cannot create Customers via the API — they are provisioned by Bandwidth.

3. You are authenticated. This guide assumes you are familiar with Bandwidth's standard API authentication. All NRM endpoints follow the same auth patterns as other Bandwidth Numbers APIs.

---

Core Concepts

Customers

In NRM, a Customer represents one of your end-customers who has been approved for NRM monitoring. Each Customer has a unique customerId that you'll reference when creating Reputation Groups.

A Customer must be registered and approved before their numbers can be monitored. You can list your available Customers at any time using the API.

Reputation Groups

A Reputation Group is the primary organizational unit in NRM. It contains a set of phone numbers that share a common business purpose. Every Reputation Group belongs to a specific Customer.

When you create a group, you specify:

• Name — A name or label associated with the numbers - visible to call recipients (like CNAM). Max 32 characters. Recommendation is to include the company name.
• Description — A short description of the group's purpose. Clarifies group purpose for NRM users.
• Intent — The type of calls being made (e.g., Customer Service, Appointment Reminders). This is passed to the carrier networks and influences how your numbers are evaluated — and is an important factor in any remediation process. See the Intent Code Reference for the full list.

Best practice: Group numbers by calling purpose. For example, create separate groups for "Sales Outbound" and "Customer Support" rather than putting all numbers in a single group. This gives you cleaner reputation data and more accurate intent signaling to carriers.

Number Reputation Status

Once numbers are added to a group, Bandwidth begins monitoring them across the three major US carriers using industry-standard analytics:

Carrier	Status Field
AT&T	attRiskRating
T-Mobile	tmobileRiskRating
Verizon	verizonRiskRating

Each number gets a per-carrier reputation rating, plus an overall carriersReputationSummary:

Status	Meaning
STATUS_PENDING	Number is being processed. Allow approximately 2 weeks for initial carrier results.
CLEAN	No labeling detected on this number.
FLAGGED	A carrier has applied a label (e.g., "Spam Likely"). Remediation begins automatically.
IN_REMEDIATION	A remediation request has been submitted to the carrier network. This typically takes 2–3 weeks.
REMEDIATION_DENIED	The remediation request was denied by the carrier's analytics system.

The remediation process is automatically triggered. When a number is flagged, Bandwidth works with carrier industry partners to initiate the remediation process with no action required from your application. The Analytics Engine ultimately decides whether the label is removed.

Status Update Schedule

Bandwidth syncs with carrier analytics networks on a weekly cycle. Status updates are reflected each Monday morning — plan any monitoring or alerting logic around this cadence.

Recommendation: If you are polling the API for status changes, check after 8:00 AM ET on Mondays.

---

Integration Walkthrough

All NRM endpoints share this base path:

https://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement

Replace {accountId} with your Bandwidth account ID.

---

Step 1: Retrieve Your Customers

Before creating any Reputation Groups, verify which of your end-customers are available in NRM.

GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/customers

Response

{
  "data": [
    {
      "customerId": 101,
      "customerName": "Acme Corp",
      "description": "Contact center customer",
      "groupCount": 0,
      "createdAt": "2025-11-01T12:00:00Z",
      "updatedAt": "2025-11-01T12:00:00Z"
    }
  ]
}

What to look for: a customer appearing in this list means they have been approved and are ready for NRM. If an expected customer is missing, their registration may still be in progress — contact your Bandwidth account team.

You can also retrieve a single customer by ID:

GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/customers/{customerId}

---

Step 2: Create a Reputation Group

Create a Reputation Group for the customer, specifying the calling purpose (intent) for the numbers you'll be monitoring. API Doc

POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/groups

Request body

{
  "name": "Acme Support Lines",
  "description": "Customer support outbound calls for Acme Corp",
  "intent": "CUSE",
  "customerId": 101
}

Note: The customerId field is required. Groups must belong to one of your registered end-users.

Response

{
  "data": {
    "groupId": 5001,
    "groupName": "Acme Support",
    "customerId": 101,
    "customerName": "Acme Corp",
    "description": "Customer support outbound calls for Acme Corp",
    "intent": "CUSE",
    "phoneNumberCount": 0,
    "createdAt": "2026-01-15T09:30:00Z"
  }
}

Record the groupId — you'll need it to add numbers.

---

Step 3: Add Numbers to the Group

Add your customer's phone numbers to the group using the bulk endpoint. Numbers must be in E.164 format (e.g., +19195551234).

POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers/bulk

Request body

{
  "action": "ADD",
  "groupId": 5001,
  "phoneNumbers": [
    "+19195551234",
    "+19195555678",
    "+19195559012"
  ]
}

Response

{
  "data": {
    "action": "ADD",
    "groupId": 5001,
    "updatedPhoneNumbers": [
      "+19195551234",
      "+19195555678",
      "+19195559012"
    ]
  },
  "errors": []
}

Check the errors array — partial success is possible if some numbers fail validation while others succeed.

Initial monitoring window: After numbers are added, expect approximately 2-3 weeks before the carrier networks complete their initial review. During this period, numbers will show a status of STATUS_PENDING.

---

Step 4: Monitor Number Reputation

Retrieve reputation status for numbers across your account. Use filters to scope results by customer, group, or status.

List all numbers for a customer:

GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers?customerId[eq]=101

Filter for flagged numbers:

GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers?customerId[eq]=101&carriersReputationSummary[eq]=FLAGGED

Response

{
  "data": [
    {
      "phoneNumber": "+19195551234",
      "groupId": 5001,
      "groupName": "Acme Support Lines",
      "customerId": 101,
      "customerName": "Acme Corp",
      "attRiskRating": "CLEAN",
      "verizonRiskRating": "FLAGGED",
      "tmobileRiskRating": "CLEAN",
      "carriersReputationSummary": "FLAGGED",
      "lastTest": "2026-01-27T00:00:00Z",
      "lastFlagged": "2026-01-27T00:00:00Z"
    }
  ],
  "page": {
    "pageNumber": 0,
    "pageSize": 50,
    "totalElements": 3,
    "totalPages": 1
  }
}

Results are paginated with a maximum page size of 50. Use pageNumber to paginate through larger result sets.

Available filters

Parameter	Description
customerId[eq]	Filter by customer ID (comma-separated for multiple)
groupId[eq]	Filter by group ID (comma-separated for multiple)
phoneNumber[eq]	Look up a specific number (E.164 format)
carriersReputationSummary[eq]	Filter by status: CLEAN, FLAGGED, or STATUS_PENDING
pageNumber	Page index (default: 0)
pageSize	Results per page (default: 50, max: 50)

---

Step 5: Get a Summary Dashboard View

Retrieve a high-level count of number statuses (e.g., to display in your customer-facing dashboard).

GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers/stats?customerId[eq]=101

Response

{
  "data": {
    "totalNumbers": 3,
    "carriersReputationSummaryCounts": {
      "CLEAN": 2,
      "FLAGGED": 1,
      "STATUS_PENDING": 0
    }
  }
}

---

Step 6: Set Up Status Notifications (Optional but Recommended)

Rather than polling the API each Monday, you can subscribe to NRM status change events and receive a webhook callback or email whenever a number's reputation changes. This is the recommended approach for production integrations.

Subscribing to NRM Events

NRM notifications use the Bandwidth Subscriptions API. Configure your subscription to receive callbacks when numbers transition between statuses.

Events that trigger a notification:

• CLEAN → FLAGGED — a number has been labeled by a carrier
• FLAGGED → CLEAN — a number's label has been successfully removed

Refer to the Subscriptions API documentation for subscription setup.

Webhook Payload

When a status change occurs, Bandwidth sends an HTTP POST to your configured endpoint.

Handling Webhook Delivery

• Respond with HTTP 200 promptly to acknowledge receipt. Any non-200 response will trigger retries.
• If your endpoint is unavailable, Bandwidth will retry delivery.
• Validate that incoming requests originate from Bandwidth before processing.

---

Managing Groups and Numbers Over Time

Updating a Group

⚠️ Once a group is submitted, its information cannot be changed since it's shared with the industry.

If you wish to change the name or description, you will need to create a new group, remove the numbers from the old group, and add them to the new group.

If the group was just created and has not been shared with the industry in the nightly sync, it can be updated via a PATCH request.

PATCHhttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/groups/{groupId}

Request body

{
  "description": "Updated: inbound support line callbacks"
}

Returns 204 No Content on success.

Moving Numbers Between Groups

Numbers cannot be moved directly between groups, but you can reassign a numbers.

1. Remove it from the current group:

POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers/bulk

{
  "action": "REMOVE",
  "phoneNumbers": ["+19195551234"]
}

2. Add it to the new group:

POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/phoneNumbers/bulk

{
  "action": "ADD",
  "groupId": 5002,
  "phoneNumbers": ["+19195551234"]
}

Deleting a Group

Delete an NRM group.

DELETEhttps://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement/groups/{groupId}

Returns 204 No Content on success.

---

Error Handling

All NRM endpoints return errors in a consistent format:

{
  "errors": [
    {
      "type": "VALIDATION_ERROR",
      "code": 400,
      "description": "Human-readable error message",
      "source": {
        "field": "intent"
      }
    }
  ]
}

Common errors to handle:

Scenario	What to expect
Invalid intent code	400 with source.field: "intent"
Missing customerId on group creation	400 with source.field: "customerId"
Number not found on your account	Error in errors array of bulk response (partial failure)
Number already assigned to a group	Error in errors array of bulk response
groupId not found	404
customerId not found or not approved	404 or 400

Partial success on bulk operations: The bulk add/remove endpoint can partially succeed. Always inspect the errors array even when the HTTP status is 200. Successfully processed numbers appear in updatedPhoneNumbers; failed numbers appear in errors with per-number detail.

---

Intent Code Reference

The intent field signals to carrier networks how the numbers in a group are being used. Choosing the most accurate intent code is important: it is evaluated by carriers when assessing number reputation and is a key factor in any remediation process. Select the code that best describes the primary calling purpose for the numbers in the group.

Code	Description
ACCS	Account Services
APPR	Appointment Reminders
APPS	Application/Signup
ATTO	Attorney
BILL	Billing
COLL	Collections
CUSE	Customer Service
DEBC	Debt Collection
EMER	Emergency
FRES	Fraud/Security
FSER	Financial Services
FUND	Fundraising
GOVN	Government
HOSP	Healthcare
INFO	Informational
INSU	Insurance
MUL	Multiple
NPF	Non-Profit
OTHE	Other
PHAR	Pharmacy
POLI	Political
REST	Restaurant
SATE	Sales/Telemarketing
SURV	Surveys

---

API Quick Reference

Operation	Method	Path
List customers	GET	/customers
Get customer	GET	/customers/{customerId}
List groups	GET	/groups
Get group	GET	/groups/{groupId}
Create group	POST	/groups
Update group	PATCH	/groups/{groupId}
Delete group	DELETE	/groups/{groupId}
Bulk add/remove numbers	POST	/phoneNumbers/bulk
List numbers with status	GET	/phoneNumbers
Get number stats	GET	/phoneNumbers/stats

All paths are relative to: https://api.bandwidth.com/api/v2/accounts/{accountId}/numberReputationManagement