Virtual Operator
The Virtual Operator provides predefined and deterministic API responses within the Vonage 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 APIs in scenarios where access to a live operator is unavailable.
Availability
The Virtual Operator is available by default to any application configured for Network APIs 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 APIs. The first entry corresponds with 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 APIS.
Responses
The Virtual Operator provides deterministic API responses based on specific parameters in the API request.
SIM Swap
The Virtual Operator always returns a response indicating that the last SIM swap event for any requested number (starting with +990) occurred exactly 500 hours before the request date. As such, the developer can send the following parameters:
| Endpoint | Parameters | Response |
|---|---|---|
/check | phoneNumber = +990XXXXXX and maxAge > 500 | swapped = true |
/check | phoneNumber = +990XXXXXX and maxAge < 500 | swapped = false |
/retrieve-date | phoneNumber = +990XXXXXX | latestSimChange 500 hours in the past |
| both | phoneNumber = +990XXXX99 | error |
Number Verification
The responses are determined by the trailing digits of the phone number provided:
| Phone Number | Response | Example |
|---|---|---|
| last digit is an even number | true | +99012345678 |
| last digit is an odd number | false | +99012345677 |
| last two digits are "99" | error | +99011111199 |
Device Location Verification
The responses are determined by the trailing digits of the phone number provided; all other fields can be set to any value. An explanation of what each verification result means can be found here. In all responses, the lastLocationTime field will show the current time:
| Phone Number | Response |
|---|---|
| Last two digits are even, e.g. "+9902345600" | A TRUE result: "verificationResult": "TRUE" "lastLocationTime": "2023-09-07T10:40:52Z" |
| Last two digits are odd, e.g. "+9902345601" | A FALSE result: "verificationResult": "FALSE" "lastLocationTime": "2023-09-07T10:40:52Z" |
| Last two digits are "11", e.g. "+9902345611" | A PARTIAL result: "verificationResult": "PARTIAL" "lastLocationTime": "2023-09-07T10:40:52Z" |
| Last two digits are "22", e.g. "+9902345622" | An UNKNOWN result: "verificationResult": "UNKNOWN" "lastLocationTime": "2023-09-07T10:40:52Z" |
Device Location Retrieval
The responses are determined by the trailing digits of the phone number provided; all other fields can be set to any value. In all responses, the lastLocationTime field will show the current time:
| Phone Number | Response |
|---|---|
| Last two digits are "11", e.g. "+9902345611" | Receive a circle response. "latitude": "50.707815" "longitude": "7.128740" "radius": 200 |
| Last two digits are "22", e.g. "+9902345622" | Receive a circle response. "latitude": "50.722112" "longitude": "7.113625" "radius": 200 |
| Last two digits are "33", e.g. "+9902345633" | Receive a circle response. "latitude": "50.737057" "longitude": "7.101254" "radius": 200 |
| Last two digits are "44", e.g. "+9902345644" | Receive a circle response. "latitude": "50.724535" "longitude": "7.093150" "radius": 200 |
| Last two digits are "55", e.g. "+9902345655" | Receive a circle response. "latitude": "50.701605" "longitude": "7.103051" "radius": 200 |
| Last two digits are "66", e.g. "+9902345666" | Receive a polygon response. {"latitude": 50.732896, "longitude": 7.102896},{"latitude": 50.731849, "longitude": 7.104989 },{"latitude": 50.732545, "longitude": 7.105906},{"latitude": 50.733659, "longitude": 7.103809} |
| Last two digits are "99", e.g. "+9902345699" | Operator Error: "status": 400 "code": "INVALID_INPUT" "message": "Virtual Operator predefined error for numbers ending with 99." |
Device Status
The responses for both the connectivity and roaming endpoints are determined by the trailing digits of the phone number provided:
/roaming
| Phone Number | Response |
|---|---|
| Last two digits are even, e.g. "+9902345600" | "roaming": true "countryCode": 234 "countryName": ["GB"] |
| Last two digits are odd, e.g. "+9902345601" | "roaming": false |
| Last two digits are "11", e.g. "+9902345611" | No country name: "roaming": true "countryCode": 901 "countryName": [] |
| Last two digits are "22", e.g. "+9902345622" | Single country name (Germany): "roaming": true "countryCode": 262 "countryName": ["DE"] |
| Last two digits are "33", e.g. "+9902345633" | Single country name (USA): "roaming": true "countryCode": 310 "countryName": ["US"] |
| Last two digits are "44", e.g. "+9902345644" | Multiple country names: "roaming": true "countryCode": 340 "countryName": ["BL", "GF", "GP", "MF", "MQ"] |
| Last two digits are "99", e.g. "+9902345699" | Operator Error: "status": 400 "code": "INVALID_INPUT" "message": "Virtual Operator predefined error for numbers ending with 99." |
/connectivity
| Phone Number | Response |
|---|---|
| Last two digits are even, e.g. "+9902345600" | Device is connected to the network via mobile data: "roaming": "CONNECTED_DATA" |
| Last two digits are odd, e.g. "+9902345601" | Device is not connected to the network: "roaming": "NOT_CONNECTED" |
| Last two digits are "11", e.g. "+9902345611" | Device is connected to the network via SMS usage: "roaming": "CONNECTED_SMS" |
| Last two digits are "99", e.g. "+9902345699" | Operator Error: "status": 400 "code": "INVALID_INPUT" "message": "Virtual Operator predefined error for numbers ending with 99." |
QoD
Responses to the Virtual Operator will always be successful, unless the last two digits are 99, which will give an error.