Reassigned Numbers Database (RND) API

Implementation Guide

Introduction

Please see the Overview Page to review account setup, authentication instructions, and other common API features.

Searchbug® offers this API service that provides access to the FCC Reassigned Numbers Database. On January 27, 2021 all service providers were required to start maintaining records of disconnected numbers. By submitting a phone number and the last date of consent to contact the consumer, you can quickly determine if the number has been reassigned or disconnected after that date.

The FCC provides a "safe harbor" for businesses using this national database. If you check the database and call a number that has not been reported as disconnected, you are protected from TCPA liability. Perform an RND query on phone numbers before contacting them to ensure you are reaching the intended receipient and stay compliant.

"Safe Harbor" does not apply until after the RND Letter of Authorization has been signed and submitted and a unique ID has been issued. Please sign and submit your RND LOA for review and approval.

Are you curious how to easily integrate this into your existing systems? This API Documentation is here to guide you!

This guide includes:

  1. Overview
  2. Sending Request
  3. Receiving Results
  4. Field Definitions in API Response
  5. Errors

Overview

Searchbug has deployed the Reassigned Number API as REST API that accepts JSON input in the Body of a POST request. The customer’s system sends a list of phone numbers with the reference date in JSON format, Searchbug processes the data, and returns the results to the client’s calling system in JSON format as well.

You can seamlessly integrate Searchbug data with your website, mobile application, intranet, network, customer database (CRM/ERP) or any other system.

Sending Request

The request should be sent to Searchbug using POST method to this endpoint:

https://data.searchbug.com/api/search.aspx

You should submit authentication and request parameters via custom POST Headers

Parameter

Value Example

Description

CO_CODE 12345678 Required. Your account number
PASS 76162c80a0333c69 API Key or account password (not needed if using Bearer Token)
TYPE api_rnd Required. Use one api_rnd for this API
FORMAT JSON Optional. The default is JSON. To get the API response in XML format, pass &FORMAT=XML

Send a list of phone numbers and dates in JSON format in the Body of your POST request. You can include any number of phone records in one request. You can send several requests consecutively and they all will be processed independently.

Use this format for your phone number list:

            
[
    {
    "phone": "<Phone>",
    "date": "<Date>"
    },
    {
    "phone": "<Phone>",
    "date": "<Date>"
    }
]

Phone is a phone number to verify. It should be 10 digits with no spaces, dashes, parenthesis or periods. Example: 2127731234

Date should be in YYYY-MM-DD format. Example: 2023-12-31.

Receiving Results

Example for a successful request in Postman

RND Receiving Results Successful Request in Postman

The results will be returned in JSON format, like this: 

                    
{
"results": [
    {
        "phone": "2143681994",
        "reassigned": "NO",
        "date": "2021-05-10"
    },
    {
        "phone": "2144594139",
        "reassigned": "YES",
        "date": "2021-06-15"
    },
    {
        "phone": "4804561831",
        "reassigned": "NO",
        "date": "2021-12-08"
    }
]                                     
}

Field Definitions in API Response

<PHONE>

10-digit phone number used for processing (e.g. 9495001234)

<REASSIGNED> Phone number reassignment status
  • YES - Queried number is contained in the database and the date the Caller provides in the query is the same as or before the permanent disconnect date for that number in the RND. (i.e., the number has been permanently disconnected during the time period).

    Example: 8505551301 was disconnected 2/11/2021. If Caller queried with 1/11/2021, result will be “YES”

  • NO - Queried number is contained in the database and the date the Caller provides in the query is after the permanent disconnect date contained in the database, or if the number is not in the database and the date the Caller provides is on or after January 27, 2021, the date all providers were required to maintain records of the most recent date each number was permanently disconnected. (i.e., the number has not been permanently disconnected during the time period).

    Example: 9105551301 was disconnected 2/11/2021. If Caller queried with 7/11/2021, result will be “NO”

  • NO_DATA - The queried number and a permanent disconnect date are not contained in the database and the date provided in the query is before January 27, 2021, the date all providers are required to maintain records of the most recent date each number was permanently disconnected numbers to the RND (i.e., the database does not contain either the date or number data queried by the Caller).

    Example: 2075551301 - Telephone number has not been disconnected. If Caller queried with 12/30/20, result will be “NO_DATA”

<DATE> Date supplied with the Reassign Number API request

Errors

In case of processing, input data or account error, the error message will be displayed instead of the results. Here are some examples: 

                    
{
"Error": "Account number, password or API Key is not valid",
}

      
                    
{
"Error": "The RND API requires a POST request. You used GET.",
}

      
                    
{
"Error": "Phone Number and Date are required parameters for the RND API. See the documentation for more details",
}

      
                    
{
"Error": "Prepaid Plan with balance is required. More info: https://www.searchbug.com/services/payment-plans-discounts.aspx/
    
Error Code: 9020204-128.36-0-C",
}

For further technical details and customer support, please chat with us, email us, or call us (800) 990-2939.

For sales and pricing information please contact sales@searchbug.com.