Advisor [Developer Preview]

The “Advisor” feature analyzes and returns advice and assessments based on Insights requested and/or available in an Identity Insights request.

Advisor is based on four static models valid for different use cases and industries:

  • Synthetic Identity: Model designed to evaluate synthetic identity risk within a customer journey.
  • Impersonation: Model designed to evaluate impersonation risk within a customer journey.
  • Account Takeover: Model designed to evaluate account take over risk within a customer journey.
  • Customer Experience: Model designed to evaluate customer experience signals within a customer journey.

These models present a level of complexity and variety of use cases that align well with the signals currently available in Identity Insights in the short to medium term. Each model contains a set of recommended Insights, signal definitions based on attribute values, and attribute ranges.

If you include the Advisor insight in the request, the response will additionally include the following for each model:

  • Recommended insights: Array with the recommended Insights for the model.
  • Signals: specific attributes and its corresponding value or value range, used to evaluate relevant aspects of a customer journey. Signals help assess risk, user experience, or compliance by highlighting meaningful patterns or anomalies in the data retrieved by Identity Insights.
  • Metrics:
    • completeness_ratio: The ratio of available (non-missing) Insights to the total number of recommended Insights, expressed as a value between 0 and 1.
    • positive_ratio: Ratio for each advice type (excluding MISSED_INSIGHT)
    • warning_ratio: Ratio for each advice type (excluding MISSED_INSIGHT)
    • negative_ratio: Ratio for each advice type (excluding MISSED_INSIGHT)
    • weighted_ratio: Weighted ratio for each advice type (excluding MISSED_INSIGHT)
  • Model Advice:
    • completeness: Advice based on the completeness_ratio metric.
    • worst_case: Advice is the worst of the available advises
    • weighted: Weigh the relevant signals and provide an overall recommendation, taking into account positive, negative, and missing signals.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

  • Creating your account,
  • Creating a Vonage application for use with the Identity Insights API,
  • The different environments available and how to configure your account to use them,
  • And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Advisor Insight programmatically using cURL.

The Identity Insights API is available via multiple regional endpoints. The examples in this guide use the EU endpoint, but you can find the full list in Technical Details.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Advisor and SIM Swap insight, to check if a SIM swap has occurred within the last 240 hours, and to obtain the analysis from that insight:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "sim_swap": {
        "period": 240
      },
      "advisor": {}
    }
  }'

The API will then analyze the response from the SIM swap insight, make an assesment, and provide advice based on it:

{
  "request_id":"c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights":{
    "sim_swap":{
      "latest_sim_swap_at":"2024-07-08T09:30:27.504Z",
      "is_swapped":true,
      "status":{
        "code":"OK",
        "message":"Success"
      }
    },
    "advisor":{
      "synthetic_identity":{
        "recommended_insights":[
          "format",
          "original_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "impersonation":{
        "recommended_insights":[
          "format",
          "original_carrier",
          "current_carrier",
          "subscriber_match"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"subscriber_match",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "account_take_over":{
        "recommended_insights":[
          "format",
          "sim_swap"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor account_take_over model."
          },
          {
            "attribute":"sim_swap",
            "advice":"NEGATIVE",
            "assessment":"A SIM swap represents a high risk of account takeover."
          }
        ],
        "metrics":{
          "completeness_ratio":0.5,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":1,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"MEDIUM",
          "worst_case":"NEGATIVE",
          "weighted":"NEGATIVE"
        }
      },
      "customer_experience":{
        "recommended_insights":[
          "format",
          "current_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "status":{
        "code":"OK",
        "message":"Success."
      }
    }
  }
}

Further Reading