Advisor [Alpha]

Advisor is a capability in the Vonage Identity Insights API that evaluates Insights, transforms them into model-specific signals, and returns an assessment with advice. This guide shows you how to use Advisor programmatically with cURL; for more information about its models, signals, and evaluations, see the Advisor Insight conceptual guide.

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.

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 analyzes the available Insight results and returns the Advisor output under the relevant model. Each model includes its signals and an evaluation object containing metrics, assessment, and advice.

"advisor": {
  "model_account_takeover": {
    "signals": [
      {
        "name": "sim_swap_detected",
        "attribute": "sim_swap.is_swapped",
        "classification": "HIGH_RISK",
        "description": "A SIM swap has been detected within the requested period."
      },
      {
        "name": "device_swap_missed",
        "attribute": "device_swap",
        "classification": "MEDIUM_RISK",
        "description": "This Insight is missed and is recommended to evaluate advisor account_takeover model"
      },
      {
        "name": "number_recycling_missed",
        "attribute": "number_recycling",
        "classification": "MEDIUM_RISK",
        "description": "This Insight is missed and is recommended to evaluate advisor account_takeover model"
      }
    ],
    "evaluation": {
      "metrics": {
        "evaluated_signals_count": 16,
        "triggered_signals_count": 3,
        "high_risk_signals_count": 1,
        "medium_risk_signals_count": 2,
        "low_risk_signals_count": 0
      },
      "assessment": "HIGH_RISK",
      "advice": "The triggered signals indicate a high likelihood of risk for this model. It is strongly recommended to apply additional security steps before proceeding with the action."
            }
  },
  "status": {
    "code": "OK",
    "message": "Success."
  }
}

Here, the status object indicates the status of the information returned for the specified phone number:

Field Description
status.code Code indicating the status of the request. Must be one of:

NO_COVERAGE: The country or mobile network is not supported by available suppliers.
INVALID_PURPOSE: The purpose used is not valid or allowed for this Insight.
UNAUTHORIZED: The request could not be authorized for the combination of application, supplier, and phone number.
INTERNAL_ERROR: An internal error occurred while processing the request.
SUPPLIER_ERROR: The supplier returned an error while processing the request.
NOT_FOUND: The phone number could not be found for this Insight.
UNSUPPORTED_NETWORK_TYPE: The network type is not supported for this Insight.
INVALID_NUMBER_FORMAT: The phone number format is not valid for assignment by carriers to users.
OUT_OF_RANGE The request specifies an input out of the time range supported by the supplier.
OK: The insight was processed successfully.
status.message More detailed status description.

If status.code in the response is OK, you may also see the fields described in the table below. If a field is marked as 'Yes' in the 'Mandatory' column, it will always be returned when the status is OK. If a field is marked as 'No', it may or may not be returned.

Field Description Mandatory
model_account_takeover Evaluation of the risk that an unauthorized party may gain access to or take control of an existing account. Yes
model_synthetic_identity Evaluation of the risk that the identity associated with this phone number is synthetic or fabricated. Yes
model_impersonation Evaluation of the risk that someone is posing as the legitimate owner of this phone number. Yes
model_mobile_number_validity Evaluation of whether the phone number is valid, plausibly associated with a legitimate subscriber, and capable of receiving mobile communications such as SMS. Yes
model_authorized_push_payment Evaluation of the risk that a user is being manipulated into authorizing a payment to a fraudster. Yes