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.

Availability

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.

After setting up the application, go to the Playground configuration page and click on "View Available Operators" to expand the list of available Network Features. The first entry corresponds with the Virtual Operator.

Virtual Operator listed on the available Network Features list within the Playground

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
    "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

The responses are preconfigured according to the phone number provided; the request should also contain any value for 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": "PARTIAL_SUCCESS",
        "message": "Unable to retrieve data for some fields."
    }
}

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

Phone number: +990123411

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

Phone number: +990123422

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

Phone number: +990123444

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

Phone number: +990123455

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

Phone number: +990123466

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

Phone number: +990123477

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

Phone number: +990123488

{
    "latest_location_at": "2023-09-07T10:40:52Z",
    "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",
    "format_valid": 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."
      }
}