Versium Analytics Data API

Versium Analytics API enables programmatic use of Versium’s Data and Predictive Scoring Services through a simple, RESTful API. JSON (default) and XML responses are provided. Both HTTP GET or HTTP POST are supported. Non-US data support is sparse and currently poorly supported. All character encodings are UTF-8, unless specified otherwise.

Value Returns
basic name, address, phone, dob
email email address, ip, originating source, timestamp
auto vehicle make, model, year, edition, trim, VIN
cell carrier, location
bus business name, address, phone, contact name, title, sic, naics, years in business, annual sales, & more
finbasic est wealth, credit rating, est income, est household income, net worth
fincredit amex, mc, visa card holder, number of credit lines, averge size of credit line & more
finmort home value, purchase date, lender name, interest rate, home age, a/c, pool, & more
eduocc education level, occupation, years in school
demobasic own/rent, gender, ethnicity, marital status, children present, language, religion & more
demodetail investing, reading, music, electronics, collectibles, home improvement, lifestyles, travel, exercise, sports, pets & more
b2bemail email address, title, business name, phone, address
rateip quality of IP address (proxy, known bad, unreliable country etc)
bounce whether or not email will bounce/report as spam.
npanxx location, carrier, valid
socmap email address, social network id & more
*note: as of June 2012, this uses ‘house data’ only; it is not a real time lookup.
socrt email address, social network id & more - real time social network lookup.
*note: as of September 2012, latency could be up to 5 seconds.

There are three types of “params” -output, configuration and query data. All configuration parameters are prefixed with “cfg_” and query parameters are prefixed with “d_”, while output is not prefixed.. output (default=’json’) -Specify JSON or XML output responses. cfg_compactor (default=1) -Record compactor will simplify record display by merging records which are very likely to be the same. Turning this feature off will increase the number of records output. cfg_recurse (default=0) -Record recursion (cfg_recurse=1) enables broad matching across widely varied data sources. This will lower overall match confidence, but can increase the number of possible matches. It is required for unusual data jumps (i.e. Social Net Handle to Vehicle VIN).

Additionally, cfg_recurse=2 enables a prematch and re-search. In this embodiment, the input query is first used to identify and score candidate matches against all eligble data sources. For example, a user may request social data by a phone number which does not exist in the social record (prodids=socmap only). cfg_recurse=2 will search across all sources with phone numbers to identify which record contains information that would be able to be used to search the socmap dataset and then performs this query cfg_bestmatchonly -This function scores all potential records that could be returned for a query and only returns back a single record which scored the highest.

Record Scoring and Matching

When a match is returned, it will include three additional values:

stats_#Recscore This score is calculated based on weighted field matches. The higher the value, the more likely the record is a match for the query. Match quality within certain fields will have a larger impact in increasing this score. For example, a query on “DAVID” will have a higher score on “DAVID” than “DAVE” than “D”. Additionally, the MatchCodes (see below) will increase the overall value here.
stats_#RecScoreUnweighted This score is calculated as above, except that the number of MatchCodes present will not impact the score.
stats_#MatchCode Match Codes can be used to discern why a particular record was returned for a given query. Some, none or all match codes may be present in a result set, separated by commas.
  • E: Email address match
  • D: DOB match
  • C: City match
  • S: State match
  • Z: ZIP Code match
  • P: Phone Number match
  • AD: Address match
  • A1: Address street name only matched
  • A2: Address house number only matched
  • A3: Address appear “very similar”
  • A4: Address appears “somewhat similar”
  • F0: First name match
  • F1: First four characters of name match
  • F2: First character of name matches
  • F3: First name alias match (BOB / ROB / ROBERT etc)
  • LF: Both First AND Last name matched, at leas partially
  • ACSZ: Address and (City/State and/or ZIP) matched, at least partially.

There are several hundred different data query parameters. As a general rule of thumb, most queries will consist of at least one of Email, Phone, Street Address, SocNetID, and optionally one or more of a Business Name, Person Name, DOB, and/or City/State/Zip.

The popular ones are listed below:

Parameter Name Data Type
d_first first name (‘Joe’)
d_last last name (‘Smith’)
d_address Full street address (‘1234 some street, suite 283’)
d_city City name (‘seattle’)
d_state State abbreviation (‘wa’)
d_zip ZIP code (‘91981’)
d_email Email address (‘person@emailprovider.com’)
d_phone Phone number (‘6195798842’)

Code Examples

http://api.versium.com/q?vkey=XXX&prodids=basic,email&d_emailaddr=ASTRO.RUNNELS @domain.com

lines wrap for easier view
{"versium":
{"ver":"1.0","req":"1.0","data":
[{"basic_#RecScore":"30",
"basic_FirstName":"JOE",
"basic_LastName":"SMITH",
"basic_Address":"500 SOMEROAD",
"basic_City":"KYLE","basic_State":"TX",
"basic_Zip":"12345","email_TimeStamp":"20110729",
"email_EmailAddr":"ASTRO.RUNNELS@domain.com",
"email_IP":"255.255.255.255"}],
"stats":{"basic":1,"email":1}}}

http://api.versium.com/q?vkey=XXX&prodids=basic,email&d_emailaddr=ASTRO.RUNNELS @domain.com&output=xml

<versium>
<ver>1.0</ver>
<req>1.0</req>
<data>
<record id="0">
<basic__recscore>30</basic__recscore>
<basic_firstname>JOE</basic_firstname>
<basic_lastname>SMITH</basic_lastname>
<basic_address>500 SOME ROAD</basic_address>
<basic_city>KYLE</basic_city>
<basic_state>TX</basic_state>
<basic_zip>12345</basic_zip>
<email_timestamp>20110729</email_timestamp>
<email_emailaddr>ASTRO.RUNNELS@domain.com</email_emailaddr>
<email_ip>255.255.255.255</email_ip>
</record>
</data>
<stats>
<basic>1</basic>< email>1
</stats>
</versium>

<versium>
<ver>1.0</ver>
<req>1.0</req>
<data>
<record id="0">
<basic__recscore>30</basic__recscore>
<basic_firstname>JOE</basic_firstname>
<basic_lastname>SMITH</basic_lastname>
<basic_address>500 SOME ROAD</basic_address>
<basic_city>KYLE</basic_city>
<basic_state>TX</basic_state>
<basic_zip>12345</basic_zip>
<email_timestamp>20110729</email_timestamp>
<email_emailaddr>ASTRO.RUNNELS@domain.com</email_emailaddr>
<email_ip>255.255.255.255</email_ip>
</record>
</data>
<stats>
<basic>1</basic>< email>1
</stats>
</versium>
<versium>
<ver>1.0</ver>
<req>1.0</req>
<data>
<record id="0">
<basic__recscore>25</basic__recscore>
<basic_firstname>Joe</basic_firstname>
<basic_lastname>Smith</basic_lastname>
<basic_address>123 fake st</basic_address>
<basic_city>fake place</basic_city>
<basic_state>ON</basic_state>
<basic_phone>1234567890</basic_phone>
<email_emailaddr>something@gmail.com</email_emailaddr>
<email_ip>255.255.255.255</email_ip>
<b2bemail_emailaddr>something@domain.com</b2bemail_emailaddr>
<b2bemail_firstname>Joe</b2bemail_firstname>
<b2bemail_lastname>Smith</b2bemail_lastname>
<b2bemail_address>123 fake st</b2bemail_address>
<b2bemail_city>fake place</b2bemail_city>
<b2bemail_state>ON</b2bemail_state>
<b2bemail_phone>1234567890</b2bemail_phone>
<cell_linetype>Landline</cell_linetype>
</record>
<stats>
<basic>1</basic>
<email>1</email>
<b2bemail>1</b2bemail>
<cell>1</cell>
</stats>
</data>
</versium>
Twitter Feed

Find out what's happening, right now, with the people and organizations you care about.


Copyright 2014 Versium Analytics