Virtual Operator for Identity Insights

The Virtual Operator provides predefined and deterministic API responses within the Network Registry Playground 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, simply select 'Playground' in your application configuration. 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 Network Features in a Playground mode. 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 Network Features.

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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}

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": "HIGH",
    "status": {
        "code": "OK",
        "message": "Success."
    }
}

Phone number: +990123433

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

Phone number: +990123444

{
    "given_name_match": "LOW",
    "family_name_match": "LOW",
    "birthdate_match": "LOW",
    "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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}

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": "PARTIAL_SUCCESS",
    "message": "Unable to retrieve data for some fields"
    }
}

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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}

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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}

Original Carrier

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

{
      "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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
      }
}

Current Carrier

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

{
      "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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
      }
}

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",
    "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",
    "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",
    "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",
    "is_reachable": false,
    "status": {
            "code": "PARTIAL_SUCCESS",
            "message": "Some response attributes were omitted because they are not applicable or were not available."
         }
    }
}

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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}

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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "is_roaming": true,
        "status": {
            "code": "PARTIAL_SUCCESS",
            "message": "Some response attributes were omitted because they are not applicable or were not available."
        }
    }
}

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",
        "is_roaming": true,
        "status": {
            "code": "PARTIAL_SUCCESS",
            "message": "Some response attributes were omitted because they are not applicable or were not available."
        }
    }
}

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

{
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_roaming": false,
        "status": {
            "code": "PARTIAL_SUCCESS",
            "message": "Some response attributes were omitted because they are not applicable or were not available."
        }
    }
}

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. For further information refer to https://developer.vonage.com/en/getting-started-network/concepts/virtual-operator."
    }
}