API Reference

Analytics API (v4)

API for retrieving analytics data from NeuroID

🚧

New v4.1 Analytics API

If you're not an existing v4 customer, please integrate against the improved v4.1 endpoint.

The Analytics API provides access to real-time behavioral profiles keyed by ID and site IDs.

See the API Endpoint sub-pages for details on how to use each endpoint. Below is an overview of responses and errors that the Analytics API returns.

📘

Note

All response objects, both successful responses and errors, return metadata about the status (e.g. SUCCESS), a status detail message, as well as a string containing moreInfo to assist in debugging any issues.

The set of possible error messages are described in Error Responses below.

Profile Response Object

You can view the response object in JSON format at the bottom of this section.

Profile Metadata

A successful response returns a profile object containing a signals list and/or an attributes list as well as the following metadata:

  • id: The ID you set in in the TrackJS client (i.e. via the setUserld JavaScript command ). This ID identifies the "Profile". This is provided in your API request as the request parameter id
    • siteId: The ID of your site/form. This is provided in your API request as the request parameter site_id.
    • funnel: If configured, the name of the funnel will be returned. One or more funnel designators can be applied to a Profile by utilizing commands available in NeuroID’s JavaScript library.
    • clientId: A NeuroID designated identifier of the browser associated with this Profile. This corresponds to a cookie that is set by NeuroID's JavaScript library.

Signals Array

signals is an array of variable size that contains signals from various models applied to the Profile. A signal may contain a non-null score and a labelstring in the response along with a model name and version.

The label is a string indicating the result of the model (e.g. “risky”, “neutral”, “genuine”, or "insufficient data").

Attributes Array

Customers who have purchased ID Attributes access can retrieve interaction and signal-level attributes from the Profiles Endpoint

Example Successful Response Objects

{
  "status": "SUCCESS",
  "message": "success",
  "moreInfo": null,
  "profile": {
    "id": "MY-USER-ID",
    "siteId": "form_mySiteID",
    "funnel": "funnelNameIfConfigured",
    "clientId": "browserID",
    "signals": [
      {
        "model": "fraud_ring_indicator",
        "version": "1.0",
        "score": 0.0,
        "label": "false"
      },
      {
        "model": "intent",
        "version": "1.0",
        "score": 98.532351,
        "label": "genuine"
      },
      {
        "model": "automated_activity",
        "version": "1.0",
        "label": "false",
        "score": 0.0,
      }
    ]
  }
}

{
  "status": "SUCCESS",
  "message": "success",
  "moreInfo": null,
  "profile": {
    "id": "MY-USER-ID",
    "siteId": "form_mySiteID",
    "funnel": "funnelNameIfConfigured",
    "clientId": "browserID",
    "interactionAttributes": {
      "interaction_time_ms": 3054,
      "unique_all_targets_count": 3,
      "client_id_count": 1,
      "unique_known_targets_count": 3,
      "unique_unknown_targets_count": 0,
      "session_id_count": 1,
      "elapsed_time_ms": 77642,
      "user_id_count": 10
    },
    "signals": [
      {
        "model": "fraud_ring_indicator",
        "version": "1.0",
        "score": 0.0,
        "label": "false",
        "attributes": {}
      },
      {
        "model": "intent",
        "version": "1.0",
        "score": 98.532351,
        "label": "genuine",
        "attributes": {
          "pii__timing__feature_1": 0,
          "pii__timing__feature_3": 4168,
          "all_text__method_of_entry__feature_1": 0,
          "pii__method_of_entry__feature_3": 0,
          "pii__interaction_patterns__feature_2": 0,
          "pii__interaction_patterns__feature_1": 0,
          "all_text__method_of_entry__feature_2": 3,
          "pii__method_of_entry__feature_1": 2,
          "pii__interaction_patterns__feature_4": 0,
          "all_text__method_of_entry__feature_3": 1,
          "pii__method_of_entry__feature_2": 0,
          "pii__interaction_patterns__feature_3": 1.1547005383792517,
          "device_type__is_pc": 0,
          "pii__interaction_patterns__feature_10": 1,
          "pii__typing_patterns__feature_5": 0.8031746031746032,
          "pii__typing_patterns__feature_4": null,
          "pii__typing_patterns__feature_7": 128.1138790035587,
          "pii__typing_patterns__feature_6": 0.8031746031746032,
          "pii__typing_patterns__feature_9": 0.7617027101012864,
          "pii__typing_patterns__feature_8": 0.7617027101012864,
          "all_text__timing__feature_1": null,
          "all_text__typing_patterns__feature_2": 0.8031746031746032,
          "all_text__timing__feature_4": 0,
          "pii__typing_patterns__feature_1": null,
          "all_text__typing_patterns__feature_1": null,
          "all_text__timing__feature_5": 0.6225264097604523,
          "all_text__timing__feature_2": 0,
          "pii__typing_patterns__feature_3": 37.634204300520736,
          "all_text__timing__feature_3": 0.33159958707145365,
          "pii__typing_patterns__feature_2": 37.634204300520736,
          "pii__transitions__feature_2": 1,
          "pii__transitions__feature_1": 1
        }
      },
      {
        "model": "automated_activity",
        "version": "1.0",
        "label": "false",
        "score": 0.0,
        "attributes": {}
      }
    ]
  }
}

Error Responses

An error response is JSON containing the status, message, and moreInfo fields with more information about what error occurred.

This section describes error codes and contains guidance for resolving issues you may encounter with the Analytics API.

Partial Success

200: SITE_NOT_CONFIGURED

NeuroID has received data for this profile but cannot calculate results because the site has not been configured.

Contact your account support rep for help configuring your site.

200: NOT_ENOUGH_INTERACTION_DATA

Each signal produced by the Neuro-ID platform requires a certain amount of data to be collected before a result can be calculated. The specific amount of data required varies by signal. In the case where a signal is unable to be calculated due to not having enough collected data, the signal label in the API response will be presented as “insufficient data,” and the score will have a null value.

Correspondingly, the status in the API response will be NOT_ENOUGH_INTERACTION_DATA to indicate that at least one reported signal could not generate results due to not meeting its minimum collected data requirements. This error can be minimized by calling the API later in the application flow to ensure enough interaction data is collected for signal generation.

Authentication and Authorization errors

401: MISSING_API_KEY

The request is missing the API key in the request headers. Check the examples above to ensure the API key Authorization header is provided and properly formatted.

Your API key can be retrieved or generated in the Customer Portal

401: UNAUTHORIZED_ACCESS

The API key header exists, but the key value appears to be missing or invalid.

401: UNAUTHORIZED_API_KEY

The API key is authorized to access the API but is not authorized to access the Site Id requested. Verify there are no typos in the siteId and that this API key is correctly associated with the Site you are requesting.

Query Errors

404: NOT_FOUND

Double-check the path if the requested URL or REST resource is not found.

404: PROFILE_NOT_FOUND

This could be caused by an ID or a site ID that is unrecognized. Ensure the ID you are requesting is the same one you set via the NeuroID JavaScript.

Verify you are providing the proper API key with access to the Site Id you request.

Server errors

500: UNKNOWN_ERROR

An unknown server error has occurred. The team is working to resolve the issue but reach out if this continues to happen.