Analytics API (v4.1)

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 NeuroID JavaScript (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 will contain a label in the response along with a model name and attributes if applicable/purchased.

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

📘
Note: This API is Intended for Real-Time Decisioning

Signals are computed in real-time as events occur and stored for later retrieval. Signals are not re-computed at API-call time.

Signals are calculated with the model version and logic that is in place at computation time, not at API call time. When new signals or models are released, they will not be applied to sessions that were computed before the release.

Computed signals are only retained for 90 days. If an API call is made more than 90 days after a session is computed the API will return 404:PROFILE_NOT_FOUND. This is true even if the session data is available in the NeuroID dashboard.

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": {
        "siteId": "form_mySiteID",
        "funnel": "funnelNameIfConfigured",
        "clientId": "browserID",
        "signals": [
            {
                "model": "familiarity",
                "label": "high"
            },
            {
                "model": "fraud_ring_indicator",
                "label": "false"
            },
            {
                "model": "automated_activity",
                "label": "false"
            },
            {
                "model": "combined_digital_intent",
                "label": "genuine"
            },
            {
                "model": "risky_device",
                "label": "false"
            }
        ],
        "id": "MY-USER-ID"
    }
}

{
    "status": "SUCCESS",
    "message": "success",
    "moreInfo": null,
    "profile": {
        "siteId": "form_mySiteID",
        "funnel": "funnelNameIfConfigured",
        "clientId": "browserID",
        "interactionAttributes": {
            "interaction_time_ms": 32487,
            "unique_all_targets_count": 5,
            "client_id_count": 1,
            "unique_known_targets_count": 5,
            "unique_unknown_targets_count": 0,
            "session_id_count": 2,
            "elapsed_time_ms": 54428,
            "user_id_count": 1
        },
        "signals": [
            {
                "model": "familiarity",
                "label": "high",
                "attributes": {
                    "other__timing__feature_2": 1,
                    "other__timing__feature_1": 0.4711393170142037,
                    "other__timing__feature_4": null,
                    "other__timing__feature_3": 0.3517169614984391,
                    "pii__method_of_entry__feature_3": 0.6,
                    "pii__method_of_entry__feature_1": 0,
                    "pii__method_of_entry__feature_2": 0,
                    "device_type__is_pc": 0,
                    "other__typing_patterns__feature_9": null,
                    "other__typing_patterns__feature_8": null,
                    "other__typing_patterns__feature_7": null,
                    "other__typing_patterns__feature_6": null,
                    "other__typing_patterns__feature_5": 51.364365971107546,
                    "other__typing_patterns__feature_4": 0.48948194662480377,
                    "all_text__typing_patterns__feature_2": 0.48948194662480377,
                    "all_text__typing_patterns__feature_1": 175.1922488983861,
                    "other__typing_patterns__feature_3": 272.9413856490071,
                    "other__interaction_patterns__feature_5": null,
                    "other__typing_patterns__feature_2": 23.5,
                    "other__interaction_patterns__feature_6": null,
                    "other__typing_patterns__feature_1": 320.3333333333333,
                    "other__interaction_patterns__feature_1": 1,
                    "other__interaction_patterns__feature_2": null,
                    "other__interaction_patterns__feature_3": null,
                    "other__interaction_patterns__feature_4": null,
                    "pii__timing__feature_1": 0.783121916842847,
                    "pii__timing__feature_2": null,
                    "pii__interaction_patterns__feature_5": null,
                    "all_text__method_of_entry__feature_1": 6,
                    "other__method_of_entry__feature_1": null,
                    "pii__interaction_patterns__feature_2": 2,
                    "pii__interaction_patterns__feature_1": 0,
                    "pii__interaction_patterns__feature_4": 0,
                    "all_text__method_of_entry__feature_2": 0,
                    "pii__interaction_patterns__feature_3": 0,
                    "all_text__method_of_entry__feature_3": 0,
                    "pii__typing_patterns__feature_5": 0.5811942230632509,
                    "pii__typing_patterns__feature_4": 234.7151656087466,
                    "pii__typing_patterns__feature_7": 48.74086108854589,
                    "pii__typing_patterns__feature_6": 0.48948194662480377,
                    "pii__typing_patterns__feature_9": -0.014812456896697216,
                    "pii__typing_patterns__feature_8": 0.0966871369294604,
                    "all_text__timing__feature_1": 1.5,
                    "other__typing_patterns__feature_11": null,
                    "pii__typing_patterns__feature_1": 34,
                    "other__typing_patterns__feature_10": null,
                    "all_text__timing__feature_4": 0,
                    "all_text__timing__feature_5": 0,
                    "pii__typing_patterns__feature_3": 102.25849597955174,
                    "all_text__timing__feature_2": 1864,
                    "pii__typing_patterns__feature_2": 313.8378732543909,
                    "all_text__timing__feature_3": 0.2620955039500008,
                    "pii__transitions__feature_2": 1,
                    "pii__transitions__feature_1": 0
                },
                "score": 97.68
            },
            {
                "model": "fraud_ring_indicator",
                "label": "false",
                "attributes": {},
                "score": 0.0
            },
            {
                "model": "automated_activity",
                "label": "false",
                "attributes": {},
                "score": 0.0
            },
            {
                "model": "combined_digital_intent",
                "label": "genuine",
                "attributes": {},
                "score": 0.0
            },
            {
                "model": "risky_device",
                "label": "false",
                "attributes": {
                    "risky_application_count": 0
                },
                "score": 0.0
            }
        ],
        "id": "MY-USER-ID"
    }
}

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. Please contact NeuroID at [email protected] to complete your site's configuration.

200: `NOT_ENOUGH_INTERACTION_DATA`

Each signal produced by the NeuroID 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 NeuroID 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

400: `BAD_REQUEST`

The request input is incorrect or malformed.

400: `MISSING_REQUIRED_QUERY_PARAMETER`

The requested URL has a missing parameter.

404: `NOT_FOUND`

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

403: `ACCESS_DENIED`

Not sufficient access to make the requested call.

404: `PROFILE_NOT_FOUND`

This could be caused by an ID or a Site Id that is unrecognized. Ensure the ID you request is the same one you set via the NeuroID JavaScript..

Verify you are providing the proper API key that has access to the Site Id you are requesting.

406: `NOT_ACCEPTABLE`

The server cannot produce a response matching the acceptable content type listed in the request headers.

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.

Analytics API (v4.1)

📘
Note

Profile Response Object

Profile Metadata

Signals Array

📘
Note: This API is Intended for Real-Time Decisioning

Attributes Array

Example Successful Response Objects

Error Responses

Partial Success

200: `SITE_NOT_CONFIGURED`

200: `NOT_ENOUGH_INTERACTION_DATA`

Authentication and Authorization errors

401: `MISSING_API_KEY`

401: `UNAUTHORIZED_ACCESS`

401: `UNAUTHORIZED_API_KEY`

Query Errors

400: `BAD_REQUEST`

400: `MISSING_REQUIRED_QUERY_PARAMETER`

404: `NOT_FOUND`

403: `ACCESS_DENIED`

404: `PROFILE_NOT_FOUND`

406: `NOT_ACCEPTABLE`

Server errors

500: `UNKNOWN_ERROR`

📘Note

Profile Response Object

Profile Metadata

Signals Array

📘Note: This API is Intended for Real-Time Decisioning

Attributes Array

Example Successful Response Objects

Error Responses

Partial Success

200: SITE_NOT_CONFIGURED

200: NOT_ENOUGH_INTERACTION_DATA

Authentication and Authorization errors

401: MISSING_API_KEY

401: UNAUTHORIZED_ACCESS

401: UNAUTHORIZED_API_KEY

Query Errors

400: BAD_REQUEST

400: MISSING_REQUIRED_QUERY_PARAMETER

404: NOT_FOUND

403: ACCESS_DENIED

404: PROFILE_NOT_FOUND

406: NOT_ACCEPTABLE

Server errors

500: UNKNOWN_ERROR

📘
Note

📘
Note: This API is Intended for Real-Time Decisioning

200: `SITE_NOT_CONFIGURED`

200: `NOT_ENOUGH_INTERACTION_DATA`

401: `MISSING_API_KEY`

401: `UNAUTHORIZED_ACCESS`

401: `UNAUTHORIZED_API_KEY`

400: `BAD_REQUEST`

400: `MISSING_REQUIRED_QUERY_PARAMETER`

404: `NOT_FOUND`

403: `ACCESS_DENIED`

404: `PROFILE_NOT_FOUND`

406: `NOT_ACCEPTABLE`

500: `UNKNOWN_ERROR`