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 - the number has been reported as reassigned after the date provided. YES response would void the express consent to contact the consumer according to FCC.
  • NO - the number has NOT been reassigned or permanently disconnected since the date provided. FCC Safe Harbor may apply.
  • NO_DATA - phone carriers have not reported any information since January 27, 2021 (the date FCC required all service providers to start maintaining records of disconnected numbers).
<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.