Web Service Documentation

Overview & Getting Started

This service is a data gateway that accepts contact elements — phone, email, name/address, MAID, hash, business, and more — and returns appended intelligence such as reverse-append name/address, phone line status, address standardization, email validation, and demographics. Three request styles are available:

Unified Single-Element GET – one input element, with "follow-along" augmentation across returned elements.
Static Multiple-Element GET – multiple input elements searched together, with no follow-along. Optimized for Salesforce & Heroku integrations.
DNC / RND / RPCV Waterfall – a compliance waterfall that screens a phone number against DNC, Reassigned Numbers Database, and Right Party Contact Verification, and returns a single PASS/FAIL disposition. Available as a single-record GET or a bulk POST.

Base URL

https://datasearch.possiblenowmarketing.com/

Authentication

Every request requires an api-key, provided by PossibleNOW during account setup. Supply it either as a URL query parameter (api-key=xxxx) or as an HTTP request header named api-key.

Environments

Use the optional env parameter to choose the target environment. Requests always go to the same Base URL above — only the env value changes where they are processed.

env value	Environment	Billing
(omitted)	Production (default)	Live data. All usage incurs direct usage costs.
`stg`	Staging	For testing and integration. Not billed as production usage.

Always validate your integration against env=stg before switching to Production.

Response Format

Responses are JSON by default. Add format=xml to receive XML instead.

Unified Single Element GET

Method: GET

Description:
This is the original Single Input Element, Multiple Request endpoint. Input only 1 contact element: Phone, Email, Person (with Address), MaID, HEM, or Business.
There are many different response types that can be requested based on the input variable. For example, if "input=phone", the system can find the person level demographics associated simply by using reverse phone append functionality to return Name and Address to match to demographic data. Likewise, other request types will perform action on returned elements from the search. For example, "input=person" and "request=wireless,active" - if the system finds the requested "wireless" phone number, it will then go into Active\Inactive check as well. Many of these scenarios exist across the endpoint enabling a "follow-along" approach to data retrieval with augmentation.

Testing of the system is permitted making sure to use the "env" URL variable to define using the Staging environment. Please note, all Production utilization will incur direct usage costs.

Parameters:

api-key – Required - provided by PossibleNOW during account setup. NOTE: This can alternatively be included as a header with the value of: "api-key".
input – Required - See available Input types and other required elements below
request – Required - See available Request types and other required elements below
format – Optional - JSON by default, "xml" if needed
env – Optional - Production environment by default, "stg" if testing

Example URL string:

GET /?request=name,address,active&input=phone&phone=7702551020&api-key=xxxx&format=json&env=stg

Example JSON Response:

{
            "input": {
                "phone": "7702551020"
            },
            "result": {
                "name": {
                    "found": true,
                    "firstname": "Test",
                    "lastname": "Customer"
                },
                "address": {
                    "found": true,
                    "address1": "4400 Rivergreen Parkway, Suite 100",
                    "city": "Duluth",
                    "state": "GA",
                    "zipcode": "30096"
                }
            },
            "transaction": {
                "queries": {
                    "Wireless Phone Reverse": -0.02
                },
                "total": -0.02,
                "accountbalance": -2.00
            },
            "status": true
          }

Input Types and Required Variables
Input Value	Description	Required variables
person	This uses name and address information to derive results	firstname, lastname, address, city, state, zipcode
phone	This 10 digit phone number to derive results	phone
email	This uses email address information to derive results	email
hash	This uses email hash information to derive results	hash, Must Include variable:hashtype (acceptable values:MD5, SHA1, SHA256)
maid	This uses a Mobile Advertising ID (MAID) to derive results	maid
ip	This uses ip address information to derive results	ip
business	This uses business name and address information to derive results	business, address, city, state, zipcode

Request Types
Request Type	Description
landline	Returns Land Line phone number
wireless	Returns Wireless phone number
address	Returns the result address associated to the result
name	Returns the Name associated to the result
cnam	Returns Caller-ID detail for any resulting or Input Phone Number
active	Returns the Active\Inactive status for any resulting or Input Phone Number. By default, only Wireless numbers are checked. Add optional parameter `activelandline=yes` to also check landlines, and `activecanada=yes` to include Canadian numbers.
carrier	Returns the Carrier status for any resulting or Input Phone Number
linetype	Returns the Line Type for any resulting or Input Phone Number
email	Returns Email Address associated to the result
cass	Returns the USPS CASS result for any resulting or Input address
dpv	Returns the USPS DPV result for any resulting or Input address
listtype	Returns the Listing Type (Res\Bus) for any resulting or Input Phone Number(s)
demographics	Returns a selected set of demographic detail for the resulting or Input Name and Address combination. Additional options below.
deactivation	Returns Mobile Phone change data (Deactivation\Resume\Suspend\Change)
eval	Validate Email Address in either Input or in append data
historical	Returns historical name and address records associated to the Input phone number. Available with `input=phone` only.
geo	Returns geocoding (latitude, longitude, and county/state FIPS codes) for the resulting or Input address

Name Response Object

The Name result object contains the result of a request with request=name

"name": {
    "found": true,
    "firstname": "SOME",
    "lastname": "NAME"
}

Variable	Description
found	"true" if returned
firstname	First Name of result
lastname	Last Name of result

Address Response Object

The Address result object contains the result of a request with request=address

"address": {
    "found": true,
    "address1": "123 Here St",
    "address2": "Suite A",
    "city": "Somewhere",
    "state": "AL",
    "zipcode": "12345",
    "zipcode4": "4321"
  }

Variable	Description
found	"true" if returned // "false" if not found
address1	Address Line of result
address2	Second Line address of result
city	City Line address of result
state	State Line address of result
zipcode	5 digit zipcode of result
zipcode4	4 digit zip code/delivery point of result

Landline Response Object

The Landline result object contains the result of a request with request=landline

"landline": {
    "found": true,
    "phone": "7275551212",
    "matchtype": "F"
}

Variable	Description
found	"true" if returned // "false" if not found
phone	Phone Number of result
matchtype	Match Type of result. "I"= Individual Match, "F"= Family/Surname Match

Wireless Response Object

The Wireless result object contains the result of a request with request=wireless

"wireless": {
    "found": true,
    "phone": "7705551212",
    "matchtype": "F"
}

Variable	Description
found	"true" if returned // "false" if not found
phone	Phone Number of result
matchtype	Match Type of result. "I"= Individual Match, "F"= Family/Surname Match

Active Response Object

The Active result object contains the result of a request with request=active

"active": {
    "found": true,
    "wireless": {
        "found": true,
        "activestatus": "yes"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
activestatus	Status of Phone Number of result or input. Yes=Active, No=Inactive

Optional parameters:

activelandline=yes – By default only wireless numbers are checked. Set this to also run the active/inactive check on landline numbers.
activecanada=yes – Include Canadian numbers in the active/inactive check.

Cnam Response Object

The Cnam result object contains the result of a request with request=cnam

"cnam": {
    "found": true,
    "input": {
        "found": true,
        "cnam": "SOME NAME"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
cnam	Caller ID information as returned by the Telecom Carrier

Linetype Response Object

The Linetype result object contains the result of a request with request=linetype

"linetype": {
    "found": true,
    "input": {
        "found": true,
        "linetype": "LANDLINE"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
linetype	Line Type information as returned by the Telecom Carrier. Values include: WIRELESS, LANDLINE, VoIP

Carrier Response Object

The Carrier result object contains the result of a request with request=carrier

"carrier": {
    "found": true,
    "input": {
        "found": true,
        "lrn": "17622046000",
        "spid": "7125",
        "ocn": "8392",
        "lata": "438",
        "city": "CALHOUN",
        "state": "GA",
        "jurisdiction": "INDETERMINATE",
        "lec": "TELEPORT COMMUNICATIONS AMERIC"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
lrn	Local Routing Number
spid	Service Provider ID
ocn	Operating Company Number
lata	Local Access and Transport Area
city	City of Carrier
state	State of Carrier
jurisdiction	Jurisdiction classification
lec	Local Exchange Carrier Name

Listtype Response Object

The Listtype result object contains the result of a request with request=listtype

"listtype": {
    "found": true,
    "input": {
        "found": true,
        "type": "Bus"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
type	Either Res or Bus

Email Response Object

The Email result object contains the result of a request with request=email

"email": {
    "found": true,
    "email": "someemail@domain.net",
    "matchtype": "I"
}

Variable	Description
found	"true" if returned // "false" if not found
email	Email Address associated with Input or Result information
matchtype	Type of match that returned Email Address. I=Individual, F=Family, A=Address

DPV Response Object

The DPV result object contains the result of a request with request=dpv

"dpv": {
    "found": true,
    "add1": "123 MAIN ST",
    "city": "SOMEWHERE",
    "state": "FL",
    "zip5": "12345",
    "zip4": "2315",
    "carrier": "C001",
    "dpvcheck": "8",
    "dpvcode": "24",
    "dpvaddrtype": "S",
    "nondeliv": "N",
    "dpvcompstatus": "0000000003333",
    "dpvresult": "Y",
    "dpvnotes": "AA BB"
}

Variable	Description
found	"true" if returned // "false" if not found
add1	Street Address
city	City
state	State
zip5	5-digit ZIP Code
zip4	ZIP+4 Code
carrier	Carrier Route
dpvcheck	Delivery Point Verification Check
dpvcode	DPV Code
dpvaddrtype	Address Type
nondeliv	Non-delivery indicator
dpvcompstatus	DPV Component Status
dpvresult	DPV Result
dpvnotes	DPV Notes

CASS Response Object

The CASS result object contains the result of a request with request=cass

"cass": {
    "found": true,
    "city": "SOMEWHERE",
    "namepart1": "FIRSTNAME",
    "namepart2": "LASTNAME",
    "streetnumber": "123",
    "predirection": "W",
    "streetname": "MAIN",
    "streetsuffix": "ST",
    "state": "NJ",
    "statuscode": "9",
    "firm": "BUSINESS NAME",
    "zip4": "2315",
    "address1": "123 W MAIN ST",
    "zip": "12345"
}

Variable	Description
found	"true" if returned // "false" if not found
city	City
namepart1	First Name
namepart2	Last Name
streetnumber	Street Number
predirection	Pre-directional
streetname	Street Name
streetsuffix	Street Suffix
state	State
statuscode	Status Code
firm	Firm or Business Name
zip4	ZIP+4
address1	Full Address Line
zip	ZIP Code

Email Validation Response Object

The Email result object contains the result of a request with request=eval

"eval": {
    "found": true,
    "result": "valid",
    "flags": [
        "free_email_host",
        "has_dns",
        "smtp_connectable"
    ]
}

Variable	Description
found	"true" if returned // "false" if not found
result	Summarized State of Email Address
flags	Object of Email Flags returned

Demographics Response Object

The request=demographics response contains default fields related to individual and household details. You can extend this response using the optional demorequest parameter to include specialized categories of data. Multiple values can be comma-separated (e.g., demorequest=realestate,financial).

usedemoname=yes – Enables use of returned name data in future lookups like Email or Phone Append.
demorequest=householdcomp – Returns data correlating to household composition.
demorequest=realestate – Returns property and real estate attributes.
demorequest=interestspurchases – Returns interests and purchasing behaviors.
demorequest=financial – Returns data on household or person financial activity.

For a complete list of fields and values, please contact your account manager.

Default Demographics Example

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE"
    }
}

Demographics + Household Composition

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE",
        "ChildrenAge00_02": "U",
        "ChildrenAge00_02Female": "U",
        "ChildrenAge00_02Male": "U",
        "ChildrenAge00_02Unknown": "U",
        "ChildrenAge03_05": "U",
        "ChildrenAge03_05Female": "U",
        "ChildrenAge03_05Male": "U",
        "ChildrenAge03_05Unknown": "U",
        "ChildrenAge06_10": "U",
        "ChildrenAge06_10Female": "U",
        "ChildrenAge06_10Male": "U",
        "ChildrenAge06_10Unknown": "U",
        "ChildrenAge11_15": "U",
        "ChildrenAge11_15Female": "U",
        "ChildrenAge11_15Male": "U",
        "ChildrenAge11_15Unknown": "U",
        "ChildrenAge16_17": "U",
        "ChildrenAge16_17Female": "U",
        "ChildrenAge16_17Male": "U",
        "ChildrenAge16_17Unknown": "U",
        "Females_18_24": "U",
        "Females_25_34": "U",
        "Females_35_44": "U",
        "Females_45_54": "U",
        "Females_55_64": "U",
        "Females_65_74": "U",
        "Females_75_Plus": "U",
        "GenerationsInHousehold": "1",
        "Grandchildren": "U",
        "Males_18_24": "U",
        "Males_25_34": "Y",
        "Males_35_44": "U",
        "Males_45_54": "U",
        "Males_55_64": "U",
        "Males_65_74": "U",
        "Males_75_Plus": "U",
        "NumberOfAdults": "1",
        "numberofpersonsinlivingunit": "1",
        "personagecode": "10",
        "personmaritalstatus": "S",
        "presenceofchildren": "N",
        "Unknowngender_18_24": "U",
        "Unknowngender_25_34": "U",
        "Unknowngender_35_44": "U",
        "Unknowngender_45_54": "U",
        "Unknowngender_55_64": "U",
        "Unknowngender_65_74": "U",
        "Unknowngender_75_Plus": "U"
    }
}

Demographics + Real Estate

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE",
        "deeddateofrefinanceday": "13",
        "deeddateofrefinancemonth": "12",
        "deeddateofrefinanceyear": "2010",
        "estimatedcurrenthomevaluecode": "G",
        "estimatedincomecode": "N",
        "homeownerprobabilitymodel": "H",
        "homepurchasedateday": "17",
        "homepurchasedatemonth": "12",
        "homepurchasedateyear": "2010",
        "homepurchaseprice": "156",
        "homepurchasepricecode": "3",
        "homeyearbuilt": "1900",
        "lengthofresidencecode": "10",
        "mortgageamountinthousandscode": "3",
        "mortgagelendername": "GRUNDY BK",
        "mortgagelendernameavailable": "Y",
        "mortgageloantype": "C",
        "mortgageratetype": "U",
        "MostRecentLenderCode": "000",
        "MostRecentLenderName2nd": "U",
        "MostRecentMortgage2ndInterestRate": "U",
        "MostRecentMortgage2ndInterestRateType": "U",
        "MostRecentMortgage2ndLoanTypeCode": "U",
        "MostRecentMortgageAmount2nd": "U",
        "MostRecentMortgageDate2nd": "U",
        "MostRecentMortgageInterestRate": "000000",
        "Purchase2ndMortgageAmount": "00000000",
        "Purchase2ndMortgageLoanTypeCode": "U",
        "PurchaseLenderCode": "000",
        "PurchaseMortgageDate": "20101213",
        "refinanceamountinthousandscode": "3",
        "refinancelendernameavailable": "Y"
    }
}

Demographics + Interests & Purchases

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE",
        "ArtsAndAntiquesAntiques": "U",
        "ArtsAndAntiquesArt": "Y",
        "AutomotiveAutoPartsAndAccessories": "U",
        "automotivebuff": "U",
        "Autowork": "U",
        "Aviation": "U",
        "BeautyCosmetics": "U",
        "BoatingSailing": "U",
        "bookbuyer": "U",
        "bookreader": "U",
        "BooksAndMagazinesMagazines": "U",
        "BooksAndMusicBooks": "U",
        "BooksAndMusicBooksAudio": "U",
        "CampingHiking": "U",
        "ChildrensApparelInfantsAndToddlers": "U",
        "ChildrensCharitableDonation": "U",
        "ChildrensInterests": "U",
        "ChildrensLearningAndActivityToys": "U",
        "ChildrensProductsGeneral": "U",
        "ChildrensProductsGeneralBabyCare": "U",
        "ChildrensProductsGeneralBackToSchool": "U",
        "CollectiblesandAntiquesGrouping": "Y",
        "CollectiblesAntiques": "Y",
        "CollectiblesArts": "U",
        "CollectiblesCoins": "U",
        "CollectiblesGeneral": "U",
        "CollectiblesSportsMemorabilia": "U",
        "CollectiblesStamps": "U",
        "CollectorAvid": "U",
        "CommunityCharities": "U",
        "computerowner": "U",
        "ComputingHomeOfficeGeneral": "U",
        "ConsumerElectronics": "U",
        "cookingenthusiast": "U",
        "CookingFoodGrouping": "U",
        "CookingGeneral": "U",
        "DIYLiving": "U",
        "ElectronicsandComputingTVVideoMovieWatcher": "U",
        "ElectronicsComputersGrouping": "U",
        "ElectronicsComputingAndHomeOffice": "U",
        "ExerciseAerobic": "U",
        "exerciseenthusiast": "U",
        "ExerciseHealthGrouping": "U",
        "ExerciseRunningJogging": "U",
        "ExerciseWalking": "U",
        "Fishing": "U",
        "FoodsNatural": "U",
        "FoodWines": "U",
        "GamesBoardGamesPuzzles": "U",
        "GamesComputerGames": "U",
        "GamesVideoGames": "U",
        "Gaming": "U",
        "GamingCasino": "Y",
        "Gardener": "U",
        "gardening_farmingbuyer": "U",
        "health_institutioncontributor": "U",
        "HealthAndBeauty": "U",
        "HealthMedical": "U",
        "Highbrow": "U",
        "HighEndAppliances": "U",
        "hightechleader": "U",
        "HistoryMilitary": "U",
        "HomeandGarden": "U",
        "homedecoratingenthusiast": "Y",
        "HomeFurnishingsDecorating": "U",
        "HousePlants": "U",
        "Hunting": "U",
        "HuntingShooting": "U",
        "LifestylesInterestsandPassionsCollectibles": "U",
        "Luggage": "U",
        "Magazines": "U",
        "MailOrderBuyer": "U",
        "mailresponder": "U",
        "MilitaryMemorabiliaWeaponry": "U",
        "Motorcycling": "U",
        "MovieCollector": "U",
        "MovieMusicGrouping": "U",
        "Musicalinstruments": "U",
        "MusicAvidListener": "U",
        "MusicCollector": "U",
        "MusicHomeStereo": "U",
        "MusicPlayer": "U",
        "Nascar": "U",
        "newsandfinancial": "U",
        "OnlinePurchasingIndicator": "U",
        "opportunityseekers": "U",
        "OtherPetOwner": "U",
        "outdoorenthusiast": "U",
        "OutdoorsGrouping": "U",
        "outdoorsportslover": "U",
        "Parenting": "U",
        "photography": "U",
        "PhotographyAndVideoEquipment": "U",
        "PoliticalCharitableDonation": "U",
        "PoliticalConservativeCharitableDonation": "U",
        "politicalcontributor": "U",
        "PoliticalLiberalCharitableDonation": "U",
        "ReadingAudioBooks": "U",
        "ReadingGeneral": "U",
        "ReadingGrouping": "U",
        "ReadingMagazines": "U",
        "ReadingScienceFiction": "U",
        "religiouscontributor": "U",
        "ReligiousInspirational": "U",
        "religiousmagazine": "U",
        "ScienceSpace": "Y",
        "ScubaDiving": "U",
        "SewingKnittingNeedlework": "U",
        "Smoker": "U",
        "Snowskiing": "U",
        "SohoIndicator": "U",
        "SpectatorSportsAutoMotorcycleRacing": "U",
        "SpectatorSportsBaseball": "U",
        "SpectatorSportsBasketball": "U",
        "SpectatorSportsFootball": "U",
        "SpectatorSportsHockey": "U",
        "SpectatorSportsSoccer": "U",
        "SpectatorSportsTVSports": "U",
        "SportsandLeisure": "U",
        "SportsGrouping": "U",
        "SportyLiving": "U",
        "sweepstakes": "U",
        "Tennis": "U",
        "TheaterPerformingArts": "U",
        "TravelAndEntertainmentCardHolder": "U",
        "TravelCruiseVacations": "U",
        "TravelDomestic": "U",
        "traveler": "Y",
        "TravelGrouping": "Y",
        "TravelInternational": "U",
        "TVCable": "U",
        "TVSatelliteDish": "U",
        "UpscaleLiving": "U",
        "Woodworking": "U",
        "YoungMensApparel": "U",
        "YoungWomensApparel": "U"
    }
}

Demographics + Financial

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE",
        "americanexpresscard": "U",
        "AmericanExpressGoldPremium": "U",
        "Credit_RangeOfNewCredit": "U",
        "CreditCardholderUnknownType": "Y",
        "CreditCardNewIssue": "U",
        "CreditCardUser": "Y",
        "CreditRating": "C",
        "DiscoverGoldPremium": "U",
        "DiscoverRegular": "U",
        "GasDeptRetailCardHolder": "U",
        "InvestingFinanceGrouping": "U",
        "investment": "U",
        "InvestmentEstimatedResidentialPropertiesOwned": "U",
        "InvestmentsForeign": "U",
        "InvestmentsPersonal": "U",
        "InvestmentsRealEstate": "U",
        "investmentstocksecurities": "U",
        "MastercardGoldPremium": "U",
        "MastercardRegular": "Y",
        "Networth": "G",
        "NumberOfLinesOfCredit": "U",
        "PresenceOfBankCard": "U",
        "PresenceOfCreditCard": "Y",
        "presenceofgoldorplatinumcreditcard": "U",
        "PresenceOfPremiumCreditCard": "U",
        "PresenceOfUpscaleRetailCard": "U",
        "refinanceloantype": "C",
        "refinanceratetype": "U",
        "VisaGoldPremium": "U",
        "VisaRegular": "U"
    }
}

Deactivation Response Object

The Deactivation result object contains the result of a request with request=deactivation

"deactivation": {
    "input": {
        "found": true,
        "results": {
            "Result": "Success",
            "Phone": "18026883918",
            "ResultRecords": 2,
            "0": {
                "MSISDN": "18026883918",
                "timeStamp": "2021-07-11",
                "OperatorName": "ATTWirelessUS",
                "MSISDNEvent": "MDN Deactivation",
                "MSISDNNew": null
            },
            "1": {
                "MSISDN": "18026883918",
                "timeStamp": "2016-07-09",
                "OperatorName": "SprintUS",
                "MSISDNEvent": "MDN Deactivation",
                "MSISDNNew": null
            }
        }
    }
}

Variable	Description
found	"true" if returned // "false" if not found
Result	Success or Failure
Phone	Phone number for results
ResultRecords	Number of result sets
MSISDN	Returned phone number
timeStamp	Date of transaction
OperatorName	Carrier Name
MSISDNEvent	Type of carrier-reported event
MSISDNNew	New number if applicable (e.g. on transfer)

Historical Response Object

The Historical result object contains the result of a request with request=historical. This request is available with input=phone only, and returns historical name and address records that have been associated to the input phone number over time.

"historical": {
    "found": true,
    "records": [
        {
            "names": [
                {
                    "prefix": "",
                    "firstName": "Jane",
                    "middleName": "R",
                    "lastName": "Sample",
                    "suffix": ""
                },
                {
                    "prefix": "",
                    "firstName": "J",
                    "middleName": "",
                    "lastName": "Sample",
                    "suffix": ""
                }
            ],
            "addresses": [
                {
                    "isDeliverable": true,
                    "houseNumber": "123",
                    "streetPreDirection": "",
                    "streetName": "Main",
                    "streetPostDirection": "",
                    "streetType": "St",
                    "unit": "4B",
                    "unitType": "Apt",
                    "city": "Anytown",
                    "state": "CA",
                    "county": "Sample",
                    "zip": "90001",
                    "zip4": "1001",
                    "fullAddress": "123 Main St, Apt 4B; Anytown, CA 90001-1001",
                    "firstReportedDate": "1/15/2021",
                    "lastReportedDate": "6/1/2026"
                },
                {
                    "isDeliverable": false,
                    "houseNumber": "500",
                    "streetPreDirection": "",
                    "streetName": "Market",
                    "streetPostDirection": "N",
                    "streetType": "Ave",
                    "unit": "12",
                    "unitType": "Apt",
                    "city": "Springfield",
                    "state": "IL",
                    "county": "Sangamon",
                    "zip": "62704",
                    "zip4": "2210",
                    "fullAddress": "500 Market Ave N, Apt 12; Springfield, IL 62704-2210",
                    "firstReportedDate": "3/1/2017",
                    "lastReportedDate": "8/20/2023"
                }
            ],
            "phones": [],
            "emails": []
        }
    ]
}

The response contains a records array. Each record groups the associated names, addresses, phones, and emails arrays for the input phone number.

Variable	Description
found	"true" if returned // "false" if not found
records	Array of historical record sets associated to the input phone number
names	Array of historical name variations (see fields below)
addresses	Array of historical addresses (see fields below)
phones	Array of historically associated phone numbers (may be empty)
emails	Array of historically associated email addresses (may be empty)

names[] Field	Description
prefix	Name prefix (e.g. Mr, Dr), if present
firstName	First name
middleName	Middle name or initial, if present
lastName	Last name
suffix	Name suffix (e.g. Jr, Sr), if present

addresses[] Field	Description
isDeliverable	"true" if the address is currently mail-deliverable
houseNumber	Street/house number
streetPreDirection	Directional preceding the street name (e.g. N, SW), if present
streetName	Street name
streetPostDirection	Directional following the street name (e.g. N), if present
streetType	Street suffix/type (e.g. Blvd, St)
unit	Unit/apartment/suite number, if present
unitType	Unit designator (e.g. Apt, Ste); null if none
city	City
state	State
county	County
zip	5-digit ZIP Code
zip4	ZIP+4 Code
fullAddress	Full formatted address string
firstReportedDate	Date this address was first reported for the individual
lastReportedDate	Date this address was most recently reported for the individual

Geo Response Object

The Geo result object contains the result of a request with request=geo. It geocodes the resulting or Input address and is available with any input that resolves to an address (e.g. person, phone, email, ip, business, hash, and static).

"geo": {
    "found": true,
    "STD_LAT": 41.338829040527,
    "STD_LONG": -88.412742614746,
    "STD_CountyFips": "063",
    "STD_StateFips": "17"
}

Variable	Description
found	"true" if returned // "false" if not found
STD_LAT	Latitude of the geocoded address
STD_LONG	Longitude of the geocoded address
STD_CountyFips	County FIPS code (3-digit) of the geocoded address
STD_StateFips	State FIPS code (2-digit) of the geocoded address

Transaction Response Object

The Transaction result object contains the result of a request with included in all responses

"transaction": {
    "queries": {
        "Wireless Reverse": -0.01,
        "CASS": -0.001,
        "Active Status": -0.01,
        "CallerID": -0.01
    },
    "total": -0.031,
    "accountbalance": 9.026
}

Variable	Description
queries	Cost per query by type
total	Total cost of queries in the transaction
accountbalance	Account balance after transaction

Static Multiple Element GET

Method: GET

Description:
This is the Multiple Contact Input Elements, Multiple Request endpoint. This allows for Name, Address, Email, Phone number details to be searched at the same time.
There are a few different options for this endpoint as it is specifically designed for Salesforce and Heroku implementations. This endpoint will perform the following actions if requested: Address Standardization, Phone Active\Inactive, Email Validation, Demographic Appends based on a profile. There are many different response types that can be requested based on the input variable. For example, if "input=phone", the system can find the person level demographics associated simply by using reverse phone append functionality to return Name and Address to match to demographic data. Be sure to input the required elements for each type of request as the system will throw an error if the request type does not have the data needed to support it. This system does not perform "follow-along" operations and specifically works within the elements provided for intelligence return.

Testing of the system is permitted making sure to use the "env" URL variable to define using the Staging environment. Please note, all Production utilization will incur direct usage costs.

Parameters:

api-key – Required - provided by PossibleNOW during account setup. Alternatively, this can be passed as a header value of: "api-key"
input – Required - Only value for this functionality = "static"
request – Required - See available Request types and other required elements below
format – Optional - JSON by default, "xml" if needed
env – Optional - Production environment by default, "stg" if testing

Example URL string:

GET /?request=dpv,active,eval,demographics&input=static&demoprofile=1&firstname=John&lastname=Doe&address=4400 Rivergreen Parkway Suite 100&city=duluth&state=GA&zipcode=30096&phone=7702551020&email=possiblenow@possiblenow.com&api-key=xxxx&format=json

Example JSON Response:

{
              "input": {
                  "address": "4400 rivergreen parkway suite 100",
                  "city": "duluth",
                  "state": "GA",
                  "zipcode": "30096",
                  "email": "possiblenow@possiblenow.com",
                  "phone": "7702551020"
              },
              "result": {
                  "dpv": {
                      "found": true,
                      "add1": "4400 RIVER GREEN PKWY STE 100",
                      "city": "DULUTH",
                      "state": "GA",
                      "zip5": "30096",
                      "zip4": "2538",
                      "carrier": "C010",
                      "dpvcheck": "7",
                      "dpvcode": "25",
                      "dpvaddrtype": "H",
                      "nondeliv": "N",
                      "dpvcompstatus": "0021010003333",
                      "dpvresult": "Y",
                      "dpvnotes": "AA BB"
                  },
                  "eval": {
                      "found": true,
                      "result": "invalid"
                  },
                  "demographics": {
                      "found": false
                  },
                  "active": {
                      "found": true,
                      "input": {
                          "found": true,
                          "activestatus": "na-landline"
                      }
                  }
              },
              "transaction": {
                  "queries": {
                      "DPV Success": -0,
                      "Email Validate Success": -0.02,
                      "CASS Address": -0.2,
                      "DemographicsProfileFailure": -0,
                      "Phone Active Status": -0.02
                  },
                  "total": -0.2,
                  "accountbalance": -2.00
              },
              "status": true
          }

Request Types
Request Type	Description
active	Returns the Active\Inactive status for any resulting or Input Phone Number. By default, only Wireless numbers are checked. Add optional parameter `activelandline=yes` to also check landlines, and `activecanada=yes` to include Canadian numbers.
dpv	Returns the USPS DPV result for any resulting or Input address
demographics	Returns a selected set of demographic detail for the resulting or Input Name and Address combination. Must include: "demoprofile" for desired options
eval	Validate Email Address in either Input or in append data
cass	Returns the USPS CASS result for the Input address. Requires address, city, state, and zipcode.
geo	Returns geocoding (latitude, longitude, and county/state FIPS codes) for the Input address. Requires address, city, state, and zipcode.

Active Response Object

The Active result object contains the result of a request with request=active

"active": {
    "found": true,
    "wireless": {
        "found": true,
        "activestatus": "yes"
    }
}

Variable	Description
found	"true" if returned // "false" if not found
activestatus	Status of Phone Number of result or input. Yes=Active, No=Inactive

Email Validation Response Object

The Email result object contains the result of a request with request=eval

"eval": {
    "found": true,
    "result": "valid",
    "flags": [
        "free_email_host",
        "has_dns",
        "smtp_connectable"
    ]
}

Variable	Description
found	"true" if returned // "false" if not found
result	Summarized State of Email Address
flags	Object of Email Flags returned

DPV Response Object

The DPV result object contains the result of a request with request=dpv

"dpv": {
    "found": true,
    "add1": "123 MAIN ST",
    "city": "SOMEWHERE",
    "state": "FL",
    "zip5": "12345",
    "zip4": "2315",
    "carrier": "C001",
    "dpvcheck": "8",
    "dpvcode": "24",
    "dpvaddrtype": "S",
    "nondeliv": "N",
    "dpvcompstatus": "0000000003333",
    "dpvresult": "Y",
    "dpvnotes": "AA BB"
}

Variable	Description
found	"true" if returned // "false" if not found
add1	Street Address
city	City
state	State
zip5	5-digit ZIP Code
zip4	ZIP+4 Code
carrier	Carrier Route
dpvcheck	Delivery Point Verification Check
dpvcode	DPV Code
dpvaddrtype	Address Type
nondeliv	Non-delivery indicator
dpvcompstatus	DPV Component Status
dpvresult	DPV Result
dpvnotes	DPV Notes

Demographics Response Object

The request=demographics response contains only fields that are pre-defined based on your specific configuration. If using this request, you must include "demoprofile" as part of the request to specify the elements returned

demoprofile=1 – Returns data correlating to profile 1.

For a complete list of fields and values, please contact your account manager.

Default Demographics Example

"demographics": {
    "found": true,
    "matchtype": "address_fullname",
    "records": {
        "countycode": "063",
        "countyname": "Grundy",
        "dpv_code": "Y",
        "dwellingtype": "S",
        "latitude": "41.359600",
        "longitude": "-88.413900",
        "persondateofbirthmonth": "3",
        "persondateofbirthyear": "1955",
        "personeducation": "U",
        "personexactage": "66",
        "personfirstname": "JOHN",
        "persongender": "M",
        "personlastname": "DOE"
    }
}

DNC / RND / RPCV Waterfall

Method: GET (single record) or POST (bulk, up to 100 records)

Description:
This is a compliance "waterfall" endpoint. A single record — name, address, phone, and last contact/consent date — is screened through up to three consecutive compliance checks and reduced to one PASS/FAIL disposition suitable for driving a dialer.

The standard order of operation is:

DNC – Do Not Call scrub against your SAN-registered project/campaign.
RND – Reassigned Numbers Database check against the supplied contactdate.
RPCV – Right Party Contact Verification: reverse-phone append plus CASS-standardized name/address comparison, followed by a wireless deactivation-date comparison.

The waterfall stops as soon as a check fails: status becomes FAIL, the remaining checks are skipped, and their result fields come back null. Changing this order requires a custom change order through your account representative, and is billable.

Prerequisites:

An active SAN subscription (and any related compliance requirements) for the DNC portion of the service. A lapse produces a FAIL response.
An active RND subscription under management for the RND portion of the service. A lapse produces a FAIL response.
The DNC, RND, and RPCV stages are each enabled per account. The method object in every response reports which stages actually ran.

Authentication: the same api-key used by the other endpoints. On GET it may be passed as a query parameter or as a header; on POST it must be a header (see Bulk Records). Passing the key in the header is the recommended practice for both.

Environments: add env=stg to target Staging. This works for both GET and POST. Staging requires a separate API key; you can request known-answer test records to validate your integration before going live. Production usage — including a capped test allowance — consists of live, billable queries.

Single Record Request (GET)

Screens one record. Both request=rpcv and input=rpcv are required, and all input fields below are required: the RPCV stage compares the supplied name and address against the reverse-phone append, and the RND stage requires the contact date.

Parameter	Description	Sample Value	Required
request	Function name. Must be `rpcv`.	rpcv	YES
input	Input type. Must be `rpcv`.	rpcv	YES
firstname	First name of the individual	John	YES
lastname	Last name of the individual	Doe	YES
address	Primary & secondary street address, including unit/apt/ste number where available	4400 Rivergreen Parkway Suite 100	YES
city	City	Duluth	YES
state	2-character state abbreviation	GA	YES
zipcode	5-digit ZIP code	30096	YES
phone	10-digit phone number. Non-numeric characters are stripped; the number must be a valid, dialable 10-digit NANP number.	7702551020	YES
contactdate	Last date of contact, or the consent date. Must be formatted `YYYY-MM-DD`.	2024-01-15	YES
api-key	Key assigned by your account representative	xxxx	NO if supplied as a header
env	Production by default, `stg` for testing	stg	NO

Example URL string (api-key in header):

GET /?request=rpcv&input=rpcv&firstname=John&lastname=Doe&address=4400 Rivergreen Parkway Suite 100&city=Duluth&state=GA&zipcode=30096&phone=7702551020&contactdate=2024-01-15&env=stg

Example URL string (api-key in URL):

GET /?api-key=xxxx&request=rpcv&input=rpcv&firstname=John&lastname=Doe&address=4400 Rivergreen Parkway Suite 100&city=Duluth&state=GA&zipcode=30096&phone=7702551020&contactdate=2024-01-15

Example JSON Response:

{
    "input": {
        "rpcv": {
            "firstname": "John",
            "lastname": "Doe",
            "address": "4400 Rivergreen Parkway Suite 100",
            "city": "Duluth",
            "state": "GA",
            "zipcode": "30096",
            "phone": "7702551020",
            "contactdate": "2024-01-15"
        }
    },
    "result": {
        "rpcv": {
            "found": true,
            "records": {
                "method": {
                    "DNC_Check": true,
                    "RND_Check": true,
                    "RPCV_Check": true
                },
                "results": {
                    "linetype": "W",
                    "active": "Y",
                    "dnc": "C",
                    "rnd": "RNN",
                    "rpcv": "1",
                    "match": "I",
                    "status": "PASS"
                }
            }
        }
    },
    "transaction": {
        "queries": {
            "Line Type": -0.02,
            "Phone Active Status": -0.02,
            "Wireless Phone Reverse": -0.02,
            "CASS Address": -0.001,
            "Deactivation Success": -0.01
        },
        "total": -0.071,
        "accountbalance": 7.922
    },
    "status": true
}

Bulk Records Request (POST)

Method: POST

Authentication: header only — api-key: xxxx

Content-Type: application/json

Screens many records in one call. The body is a JSON-encoded object containing an rpcvList array, and the response is JSON-encoded. Each element takes the same eight input fields as the GET request.

Important: on a POST, the query string is not forwarded upstream. The api-key must therefore be supplied as a request header — a key placed in the URL will not authenticate. The one query parameter that still has an effect is env=stg, which selects the Staging environment before the query string is dropped.

Batch size: the gateway rejects a payload of more than 100 records with Input Quantity Exceeds Limit. We recommend batches of 10 records or fewer unless your account representative confirms a higher volume for your account.

Example request:

POST /?env=stg
api-key: xxxx
Content-Type: application/json

Example JSON body:

{
    "rpcvList": [
        {
            "firstname": "John",
            "lastname": "Doe",
            "address": "4400 Rivergreen Parkway Suite 100",
            "city": "Duluth",
            "state": "GA",
            "zipcode": "30096",
            "phone": "7702551020",
            "contactdate": "2024-01-15"
        },
        {
            "firstname": "Jane",
            "lastname": "Sample",
            "address": "100 Main St",
            "city": "Sarasota",
            "state": "FL",
            "zipcode": "34243",
            "phone": "9415551212",
            "contactdate": "2021-01-15"
        }
    ]
}

Example JSON Response:

Records are returned in the order they were submitted, each echoing its own input alongside its results. The second record below failed the DNC stage, so the RND and RPCV fields were never populated.

{
    "method": {
        "DNC_Check": true,
        "RND_Check": true,
        "RPCV_Check": true
    },
    "records": [
        {
            "input": {
                "firstname": "John",
                "lastname": "Doe",
                "address": "4400 Rivergreen Parkway Suite 100",
                "city": "Duluth",
                "state": "GA",
                "zipcode": "30096",
                "phone": "7702551020",
                "contactdate": "2024-01-15"
            },
            "results": {
                "linetype": "W",
                "active": "Y",
                "dnc": "C",
                "rnd": "RND",
                "rpcv": "1",
                "match": "I",
                "status": "PASS"
            }
        },
        {
            "input": {
                "firstname": "Jane",
                "lastname": "Sample",
                "address": "100 Main St",
                "city": "Sarasota",
                "state": "FL",
                "zipcode": "34243",
                "phone": "9415551212",
                "contactdate": "2021-01-15"
            },
            "results": {
                "linetype": "L",
                "active": "Y",
                "dnc": "D",
                "rnd": null,
                "rpcv": null,
                "match": null,
                "status": "FAIL"
            }
        }
    ],
    "transaction": {
        "queries": {
            "Line Type": {
                "cost": -0.04,
                "quantity": 2
            },
            "Phone Active Status": {
                "cost": -0.04,
                "quantity": 2
            },
            "DNCCOMSuccess": {
                "cost": 0,
                "quantity": 1
            },
            "RNDSuccess": {
                "cost": 0,
                "quantity": 1
            },
            "Wireless Phone Reverse": {
                "cost": -0.02,
                "quantity": 1
            },
            "CASS Address": {
                "cost": -0.003,
                "quantity": 3
            },
            "Deactivation Success": {
                "cost": -0.01,
                "quantity": 1
            }
        },
        "total": -0.113,
        "accountbalance": 98.455
    },
    "status": true
}

Note the difference in the transaction.queries shape: the single-record GET reports a scalar cost per query type, while the bulk POST reports an object with cost and quantity per query type.

Method Object

Every response reports which stages of the waterfall are enabled for your account. A stage reported as false did not run, and its corresponding result field will be null for every record.

Variable	Description
DNC_Check	"true" if the DNC scrub is enabled for your account
RND_Check	"true" if the Reassigned Numbers Database check is enabled for your account
RPCV_Check	"true" if Right Party Contact Verification is enabled for your account

Results Object

The results object is identical in both the single and bulk responses. Any field belonging to a stage that was skipped — because it is not enabled, or because an earlier stage failed — is returned as null.

Variable	Description	Values
linetype	Line type of the input phone number	W, L, V, O
active	Active/inactive status of the input phone number at time of query	Y, N
dnc	Result of the DNC scrub	C, D, B, I
rnd	Result of the Reassigned Numbers Database check	RNN, RND, RNY, RNE, RTL, RAE
rpcv	RPCV score from the deactivation-date comparison	1, 2, 3
match	Level at which the input name and address matched the phone number	I, F, A, V, N, U
status	Overall disposition of the record	PASS, FAIL
error	Bulk POST only. Present when a record was rejected before the waterfall ran.	"Invalid Phone", "Invalid Contact Date"

DNC Result Codes

Code	Definition	Status
C	Callable – the input phone number meets all preset compliance parameters. This record continues to the RND stage.	Pass
D	DNC – the input phone number matches a DNC database and is not callable. The waterfall stops here.	Fail
B	Blocked – the input number's area code is not registered on your SAN. The waterfall stops here.	Fail
I	Invalid – the record is missing the date information required to process through RND.	Fail

RND Result Codes

Only RNN and RND continue to the RPCV stage. Every other value stops the waterfall with status: "FAIL".

Code	Definition	Status
RNN	The input phone number is not reassigned (RND equivalent: "no"). This record continues to the RPCV stage.	Pass
RND	No data present for the phone number (RND equivalent: "no_data"). Occurs when the consent date precedes January 27, 2021. This record continues to the RPCV stage.	Pass
RNY	The input phone number is reassigned. Does not continue to RPCV.	Fail
RNE, RTL, RAE	Error, throttle, or authentication conditions returned by the RND service. Does not continue to RPCV. An `RAE` or `RTL` will stop the remainder of the process.	Fail

RPCV Score

The rpcv field compares the contactdate you supplied against the most recent deactivation/change date reported by the mobile carrier. Landlines and other non-wireless line types skip the carrier comparison entirely.

Score	Definition	Status
1	The carrier's date of change is older than the date you provided – the number has not changed ownership (it may have been ported by the same person).	Pass
2	The date you provided is older than the carrier's date of change – the number has changed ownership or been disconnected.	Pass
3	Not a wireless number (landline, VoIP, or other), so no carrier change date applies.	Pass

Match Level

The match field reports how closely the name and address you supplied line up with the party associated with the phone number. The input address is CASS-standardized before comparison.

Code	Definition	Status
I	Individual match level – first name, last name, and address all match the phone number.	Pass
F	Household match level – last name and address match the phone number.	Pass/Fail
A	Address match level – the address matches the phone number, but the name does not.	Pass/Fail
V	The input contact name and address are verified.	Pass
N	The input contact name and address are not verified.	Pass
U	Not found / not valid.	Pass

I, F, and A are the direct reverse-phone-append comparisons. If none of those match, the record falls through to a demographic match, which is what returns V, N, or U. Whether an F or A is acceptable for your campaign is a policy decision — the waterfall itself does not fail a record on match level.

Phone Status & Line Type

Both fields are populated at the start of the waterfall, before the DNC stage, and are returned for every record.

Field	Definition	Values
active	Live, active, or inactive status of the input number at time of query	Y = Active N = Inactive
linetype	How the input phone number is coded	W = Wireless L = Landline V = VoIP O = Other

Errors

Configuration and payload problems return HTTP 400 with a body of {"status": false, "error": "…"}. Per-record problems in a bulk POST do not fail the whole call — that record is returned with status: "FAIL" and an error field in its results object.

Message	Scope	Meaning
rpcv error: no configuration for user	Whole request	The account has no RPCV configuration. Contact your account representative.
rpcv error: DNC selected but not configured for user	Whole request	The DNC stage is enabled but the account is missing its DNC credentials.
rpcv error: RND selected but not configured for user	Whole request	The RND stage is enabled but the account is missing its RND credentials.
rpcv error: RND selected but invalid contact date	Whole request (GET)	The RND stage is enabled and `contactdate` is missing or not in `YYYY-MM-DD` format.
rpcv error: invalid phone	Whole request (GET)	`phone` is not a valid 10-digit number.
Invalid JSON Input	Whole request (POST)	The body could not be parsed, or it contains no `rpcvList` array.
Input Quantity Exceeds Limit	Whole request (POST)	More than 100 records were submitted in one payload.
Invalid Phone	Single record (POST)	That record's `phone` is not a valid 10-digit number. Returned in `results.error`.
Invalid Contact Date	Single record (POST)	That record's `contactdate` is missing or not in `YYYY-MM-DD` format. Returned in `results.error`.

Overview & Getting Started

Unified Single Element GET

Response Types

Static Multiple Element GET

Response Types

DNC / RND / RPCV Waterfall

Requests

Result Codes

Web Service Documentation

Overview & Getting Started

Base URL

Authentication

Environments

Response Format

Unified Single Element GET

Name Response Object

Address Response Object

Landline Response Object

Wireless Response Object

Active Response Object

Cnam Response Object

Linetype Response Object

Carrier Response Object

Listtype Response Object

Email Response Object

DPV Response Object

CASS Response Object

Email Validation Response Object

Demographics Response Object

Default Demographics Example

Demographics + Household Composition

Demographics + Real Estate

Demographics + Interests & Purchases

Demographics + Financial

Deactivation Response Object

Historical Response Object

Geo Response Object

Transaction Response Object

Static Multiple Element GET

Active Response Object

Email Validation Response Object

DPV Response Object

Demographics Response Object

Default Demographics Example

DNC / RND / RPCV Waterfall

Single Record Request (GET)

Bulk Records Request (POST)

Method Object

Results Object

DNC Result Codes

RND Result Codes

RPCV Score

Match Level

Phone Status & Line Type

Errors