Virtual Operator for Identity Insights

The Virtual Operator provides predefined and deterministic API responses within the Network Registry when using phone numbers associated with the unassigned country code +990. It can be used as a simulated operator for discovery, development and testing of Network Features in scenarios where access to a live operator is unavailable.

To use the Virtual Operator, enable Network Features in your application and select the 'Test access' type. All API calls directed to phone numbers with the +990 prefix will automatically be redirected to the Virtual Operator.

All API calls made using the Virtual Operator require to implement the same authentication flows as those made through a regular mobile operator.

The Virtual Operator is available by default to any application configured for Vonage Network Features in a Network Registry. No further configuration is necessary to use the Virtual Operator.

It is not necessary to add +990 numbers to your allowlist. Simply make an API call to any of the supported Vonage Network Features.

Responses

There are 10 phone numbers available for testing with the Virtual Operator: +990123400, +990123411, +990123422, +990123433, +990123444, +990123455, +990123466, +990123477, +990123488, and +990123499.

The responses to requests using these phone numbers will vary according to the insight you are using; these responses are documented below.

SIM Swap

Using any of these phone numbers will give the same response: +990123400, +990123411, +990123422, +990123433, +990123444, +990123455, +990123466, +990123477, +990123488

{
    "latest_sim_swap_at": "2017-11-14T01:07:28Z", // 500 hours ago
    "is_swapped": false, // true if period < 500 hours, false if period > 500 hours
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Using the phone number +990123499 will return an unknown phone number response:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "Unknown phone number."
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Subscriber Match

Match responses are returned according to the phone number provided; the request may contain any, but at least one supported attribute. In the following example, the user requested given_name, family_name, and birthdate:

Phone number: +990123400

{
    "given_name_match": "DATA_UNAVAILABLE",
    "family_name_match": "DATA_UNAVAILABLE",
    "birthdate_match": "DATA_UNAVAILABLE",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123411 or +990123477

{
    "given_name_match": "EXACT",
    "family_name_match": "EXACT",
    "birthdate_match": "EXACT",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123422

{
    "given_name_match": "HIGH",
    "family_name_match": "HIGH",
    "birthdate_match": "NONE",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123433

{
    "given_name_match": "PARTIAL",
    "family_name_match": "PARTIAL",
    "birthdate_match": "NONE",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123444

{
    "given_name_match": "LOW",
    "family_name_match": "LOW",
    "birthdate_match": "NONE",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123455, +990123466 or +990123488

{
    "given_name_match": "NONE",
    "family_name_match": "NONE",
    "birthdate_match": "NONE",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123499

{
    "status": {
        "code": "NOT_FOUND",
        "message": "Unknown phone number."
    }
}

Any other +990 number

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Location Verification

The responses are determined by the phone number provided; all other fields can be set to any value. An explanation of what each verification result means can be found in the API specification:

Phone number: +990123400

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "TRUE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123411

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "PARTIAL",
    "match_rate": 50,
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123422

{
    "is_verified": "UNKNOWN",
    "status": {
        "code": "OK",
        "message": "The insight was processed successfully."
      }
}

Phone number: +990123433

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "FALSE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123444

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "TRUE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123455

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "FALSE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123466

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "TRUE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123477

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "FALSE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123488

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "is_verified": "TRUE",
    "status": {
    "code": "OK",
    "message": "Success"
    }
}

Phone number: +990123499

{
    "status": {
    "code": "NOT_FOUND",
    "message": "Unknown phone number."
    }
}

Any other +990 number

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Format

Using any of these phone numbers will give the same response: +990123400, +990123411, +990123422, +990123433, +990123444, +990123455, +990123466, +990123477, +990123488, +990123499

{
    "country_code": "XX",
    "country_name": "Virtual",
    "country_prefix": "990",
    "offline_location": "Virtual",
    "time_zones": ["UTC"],
    "number_international": "+990123411",
    "number_national": "123411",
    "is_valid_format": true,
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Original Carrier

{
      "name": "Virtual CSP",
      "network_type": "MOBILE",
      "country_code": "XX",
      "network_code": "00101",
      "status": {
            "code": "OK",
            "message": "Success"
      }
}

Using any other +990 number will return an error:

{
      "status": {
            "code": "INVALID_NUMBER_FORMAT",
            "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
      }
}

Current Carrier

{
      "name": "Virtual CSP",
      "network_type": "MOBILE",
      "country_code": "XX",
      "network_code": "00101",
      "status": {
            "code": "OK",
            "message": "Success"
      }
}

Using any other +990 number will return an error:

{
      "status": {
            "code": "INVALID_NUMBER_FORMAT",
            "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
      }
}

Reachability

The responses are determined by the phone number provided; all other fields can be set to any value. An explanation of what each verification result means can be found in the API specification.

In all responses, latest_status_at will return the current time minus 2 minutes.

Phone numbers: +990123400, +990123444 and +990123488 all return connected with data and SMS:

{
"reachability": {
    "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
    "is_reachable": true,
    "connectivity": ["DATA","SMS"],
    "status": {
            "code": "OK",
            "message": "Success"
         }
    }
}

Phone numbers: +990123411 or +990123455 both return connected with data:

{
"reachability": {
    "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
    "is_reachable": true,
    "connectivity": ["DATA"],
    "status": {
            "code": "OK",
            "message": "Success"
         }
    }
}

Phone numbers: +990123422 or +990123466 both return connected with SMS:

{
"reachability": {
    "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
    "is_reachable": true,
    "connectivity": ["SMS"],
    "status": {
            "code": "OK",
            "message": "Success"
         }
    }
}

Phone numbers: +990123433 or +990123477 both return not reachable:

{
"reachability": {
    "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
    "is_reachable": false,
    "status": {
            "code": "OK",
            "message": "Success"
         }
    }
}

Phone number: +990123499 returns phone number not found:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight"
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Roaming

The responses are determined by the phone number provided; all other fields can be set to any value. An explanation of what each verification result means can be found in the API specification.

In all responses, latest_status_at will return the current time minus 2 minutes.

Phone number: +990123400 returns is_roaming is true, country code "GB":

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "country_codes": ["GB"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123411 returns is_roaming is true, country code "DE":

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "country_codes": ["DE"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123422 returns is_roaming is true, country code "US":

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "country_codes": ["US"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123433 returns is_roaming is true, with multiple country codes:

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "country_codes": ["BL,GF,GP,MF,MQ"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123444 returns is_roaming is true, country code "BR":

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "country_codes": ["BR"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123455 returns is_roaming is true, but with no country code:

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123466 returns is_roaming is true, but no country code could be identified:

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": true,
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone numbers: +990123477 and +990123488 both return is_roaming as false:

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z", // 120 seconds ago
        "is_roaming": false,
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
}

Phone number: +990123499 returns phone number not found:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight"
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Device Swap

Using any of these phone numbers will give the same response: +990123400, +990123411, +990123422, +990123433, +990123444, +990123455, +990123466, +990123477, +990123488

{
    "latest_device_swap_at": "2017-11-14T01:07:28Z", // 500 hours ago
    "is_swapped": true, // false if period < 500 hours, true if period >= 500 hours
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Using the phone number +990123499 will return an unknown phone number response:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight."
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Subscriber Tenure

Using different virtual phone numbers will provide different responses, as showcased below.

Phone numbers: +990123400, +990123411, +990123422

{
"is_tenure_met": true, // false if date is >180 days ago
    "contract_type": "PREPAID",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone numbers: +990123433, +990123444, +990123455

{    
    "is_tenure_met": true, // false if date is >180 days ago
    "contract_type": "POSTPAID",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phones: +990123466, +990123477

{    
    "is_tenure_met": true, // false if date is >180 days ago
    "contract_type": "BUSINESS",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone number: +990123488

{    
    "is_tenure_met": true, // or false based on L3
    "status": {
        "code": "SUCCESS",
        "message": "Unable to retrieve data for some fields"
    }
}

Using the phone number +990123499 will return an unknown phone number response:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight."
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Age Verification

For this insight, the responses vary depending on the phone number used.

Phone numbers: +990123400, +990123411

{    
    "is_age_threshold_met": "TRUE", // age=12
    "is_verified": true,
    "identity_match_score": 100,
    "content_lock": "TRUE",
    "parental_control": "TRUE",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone numbers: +990123422, +990123433

{    
    "is_age_threshold_met": "TRUE", // age=23
    "is_verified": true,
    "identity_match_score": 70,
    "content_lock": "FALSE",
    "parental_control": "FALSE",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone numbers: +990123444, +990123455

{    
    "is_age_threshold_met": "TRUE", // age=37
    "is_verified": false,
    "identity_match_score": 50,
    "content_lock": "TRUE",
    "parental_control": "TRUE",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone numbers: +990123466

{    
    "is_age_threshold_met": "TRUE", // age=15
    "is_verified": false,
    "identity_match_score": 30,
    "content_lock": "TRUE",
    "parental_control": "TRUE",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Phone numbers: +990123477

{
    "is_age_threshold_met": "DATA_UNAVAILABLE",
    "status": { 
        "code": "OK", 
        "message": "Success" 
    } 
}

Phone numbers: +990123488

{    
    "is_age_threshold_met": "TRUE", // age=20
    "is_verified": false,
    "identity_match_score": 0,
    "content_lock": "TRUE",
    "parental_control": "TRUE",
    "status": {
        "code": "OK",
        "message": "Success"
    }
}

Using the phone number +990123499 will return an unknown phone number response:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight."
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}

Number Recycling

The response from the virtual operator will change depending on the phone number provided:

Phone Numbers: +990123400, +990123411, +990123422

{
	"is_number_recycled": true, // LAST_RECYCLED_DATE=TODAY - 1 day
      "status": {
          "code": "OK",
          "message": "Success"
      }
}

Phone Numbers: +990123433, +990123444, +990123455

{    
  	"is_number_recycled": true, // LAST_RECYCLED_DATE=TODAY - 7 days
     "status": {
          "code": "OK",
          "message": "Success"
      }
}

Phone Number: +990123466

{    
     "is_number_recycled": true, // LAST_RECYCLED_DATE=TODAY - 30 days
     "status": {
         "code": "OK",
         "message": "Success"
      }
}

Phone Number: +990123477

{    
"is_number_recycled": true, // LAST_RECYCLED_DATE=TODAY - 90 days
     "status": {
         "code": "OK",
         "message": "Success"
      }
}

Phone Number: +990123488

{    
  	"is_number_recycled": true, // LAST_RECYCLED_DATE=TODAY - 180 days
     "status": {
         "code": "OK",
         "message": "Success"
      }
}

Using the phone number +990123499 will return an unknown phone number response:

{
    "status": {
        "code": "NOT_FOUND",
        "message": "The phone number could not be found for this Insight."
    }
}

Using any other +990 number will return an error:

{
    "status": {
        "code": "INVALID_NUMBER_FORMAT",
        "message": "Invalid number. Only the following Virtual Operator numbers are allowed: 990123400, 990123411, 990123422, 990123433, 990123444, 990123455, 990123466, 990123477, 990123488, 990123499."
    }
}