Commercial Opt-Out API

Implementation Guide

Introduction

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

Searchbug® Commercial Opt-Out API provides a structured, auditable way for commercial organizations to submit opt-out and removal requests on behalf of their customers.

Overview

Searchbug has deployed the Commercial Opt-Out API as REST API that accepts JSON input in the Body of a POST request. The customer’s system sends a person's name and known contact information (emails, phone numbers, and addresses in JSON format, Searchbug processes the data, and returns the blocking results to the client’s calling system in JSON format as well.

Sending Request

The request should be sent to Searchbug using the following URL using the following URL using the POST method:

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

Request Parameters

You should submit authentication and request parameters via custom POST Headers

Parameter Value Example Description
CO_CODE 1279999 Required. Your account number
PASS 76162c80a0333c91 API Key or account password (not needed if using Bearer Token)
TYPE api_block Required. Use "api_block" for this API

Send the person's name and known contact information, in JSON format, in the Body of your POST request. Include all data about one person in one request. The request should contain full name (first, middle, and last), plus one, many, or none of associated emails, addresses, or phone numbers. You also optionally supply reference_id and the reason for blocking request. They will be included in the response, if provided.

Use this format for your removal/blocking request: 


{	
  "first_name": "<FirstName>",
  "middle_name": "<MiddleName>",
  "last_name": "<LastName>",
  "emails": [
        "<Email>",    
        "<Email>"    
    ],   
  "addresses": [
        "<Address>",
        "<Address>"
    ],
  "phone_numbers": [
        "<Phone>",
        "<Phone>",
        "<Phone>"
        
    ],
    "reference_id": "<Ref_ID>",
    "reason": "<Reason>"

  }

Field Definitions in API Request

Parameter Value Example Description
<FirstName> Martha Required. FirstName
<MiddleName> R Optional. Middle name or Middle initial
<Email> MarthaJohnson@gmail.com Optional. Email Address in a valid format. One, many, or none. If none, skip the "emails" node.
<Address> 123 Main St, Atlanta, GA 03214 Optional. Street Address in postal format. Do not include the unit number. One, many, or none. If none, skip the "addresses" node.
<Phone> 2127731234

Optional. Phone number. One, many, or none. If none, skip the "phone_number" node.

The phone numbers can be in any format. They can contain spaces, dashes, parentheses, or periods. Examples: 212-773-1234, 2127731234, 212.773.1234, (212) 773-1234.
<Ref_ID> R95346834095836 Optional. Internal Reference ID. Included in the response, if provided.
<Reason> Personal Request Optional. Removal Reason. Included in the response, if provided.

Examples of valid JSON Body requests:

Example of JSON Body Request 1
Example of JSON Body Request 2
Example of JSON Body Request 3

Receiving Removal Responses

Ref_ID and Reason were provided. The record was previously blocked. No action was needed.

                        
{
    "id": "095346834095837",
    "status": "previously_blocked",
    "reason": "Personal Request"
  }

Ref_ID and Reason were NOT provided. Blocking has been completed.

                               
{
    "id": "",
    "status": "completed",
    "reason": ""
  }

Field Definitions in API Response

Parameter Value Example Description
id 095346834095837 Internal Reference ID. Included in the response, if provided.
status completed

previously_blocked: The record was previously blocked. No action was needed

completed: Blocking has been successfully completed.

internal_error: Could not block the record due to technical problem or missing name, which is required.
reason Personal Request Removal Reason. Included in the response, if provided.

Errors

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

API Block Error 1
API Block Error 2
API Block Error 3
API Block Error 4

Checking API Prepaid Balance

To check your current prepaid balance, please use the following URL format over HTTPS. Use TYPE_API specific to the API type for which you want to get the stats. This example is for api_loc2. Use 'api_block' for this API.

https://data.searchbug.com/api/search.aspx?CO_CODE=<AccountID>&PASS=<Password>&TYPE=STATUS&TYPE_API=api_loc2 

<RESULTS>
    <API_TYPE>api_loc2</API_TYPE>
    <API_NAME>API - Line Type and Carrier (Standard)</API_NAME>
    <DAILY>1</DAILY>
    <MONTHLY>4</MONTHLY>
    <RATE>0.0100</RATE>
    <BALANCE>47.72</BALANCE>
    <PREPAID>100.00</PREPAID>
    <DATE>01/12/2023</DATE>
</RESULTS>

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.