Realtime User Scoring/Profiling

The TrueStats user profiling and scoring API provides the ability to get real-time intel on your users from any platform you are using. It uses a standard REST interface that returns a JSON object with the profile data. It can be integrated into any major platform.


One of the simplest ways to access the API is with an HTTPS call. Click on the link below for an example using our free version:

This returns a JSON object with the user's score and profile. An example with comments:
    "code": 200,                            //  the HTTP status code of the call - 200 means the call was successfully processed
    "data": {
        "score": 520,                       //  a score less than 100 indicates a very high likelyhood of a bot or an invalid user
        "offense": null,                    //  this identifies the primary reason a user has a low score (colocation, collusion, etc.)
        "organization": "Acme, Inc.",       //  the company, ISP, school or governmental agency of the user
        "searchInfo": {                     //  we detect over 200 search engines
            "group": "Bing",
            "name": "Bing",
            "keys": "bicycles"
        "campaign": "BingAds",              //  the pay version aggregates on dozens of attributes, including campaign, source, publisher id,
                                            //  medium, channel, etc.

        "deviceType": "Mobile",             //  can also be desktop/laptop, tablet, console, TV and handheld.
        "platformVersion": "iOS 9.2",
        "platform": "iOS",
        "isUniversity": false,              //  whether the user is within a university's netblock
        "geolocation": {                    //  I.P. based geolocation for web users - this is 100% accurate to the country and
                                            //  roughly 85% accurate to the postal code level.
            "countryCode": "US",
            "countryName": "United States",
            "region": "CA",
            "city": "Laguna Niguel",
            "postalCode": "92677",
            "latitude": 33.5351,
            "longitude": -117.7052,
            "dmaCode": 803,                 //  a Designated Market Area (DMA) is a group of counties in the United States that are
                                            //  covered by a specific group of television stations.
            "areaCode": 949,
            "continentCode": "NA",
            "regionName": "California"
        "demographics": {                   //  these are demographics for the postal code the user is in
            "medianHouseholdIncome": 112620,
            "averageHomeValue": 798918,
            "percentWhite": 77.56,
            "percentBlack": 1.44,
            "percentHispanic": 15.81,
            "percentAsian": 10.24,
            "percentFemale": 51.35,
            "percent0_14": 21.4,
            "percent15_24": 12.1,
            "percent25_34": 10,
            "percent35_44": 15.3,
            "percent45_54": 18.3,
            "percent55_64": 12.7,
            "percent65Over": 10.1
        "browserVersion": "Safari",
        "browser": "Safari",
        "status": "This result was delayed intentionally as part of the free version.  Create an account at for full speed access."

Error Codes

Any code returned other than 200 indicates an error. The "message" property will describe the error. For example:
    "code": 400,
    "message": "Missing parameter(s): I.P. address"

Implementation Examples

All major platforms support REST interfaces. Here are a few examples on platform-specific implementations:


The scoring API is engineered to be extremely fast, returning data in under 5 milliseconds. However, internet latency will add to that time. Therefore, our API can be co-located at the datacenter your servers reside at, which will allow for near real-time access to user information. Please contact us for more information.