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. Two 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.

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"
    }
}

Overview & Getting Started

Unified Single Element GET

Response Types

Static Multiple Element GET

Response Types

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