{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/vonage/main/json-schema/vonage-ni-response-json-advanced-sync-schema.json",
"title": "niResponseJsonAdvancedSync",
"description": "Advanced Response (sync)",
"x-generated": "2026-10-08",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/vonage-number-insight-openapi.yml#/components/schemas/niResponseJsonAdvancedSync",
"type": "object",
"properties": {
"status": {
"$ref": "#/$defs/niStandardAdvancedStatus"
},
"status_message": {
"type": "string",
"description": "The status description of your request."
},
"request_id": {
"type": "string",
"description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.",
"maxLength": 40
},
"international_format_number": {
"type": "string",
"description": "The `number` in your request in international format."
},
"national_format_number": {
"type": "string",
"description": "The `number` in your request in the format used by the country the number belongs to."
},
"country_code": {
"type": "string",
"description": "Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.",
"pattern": "[A-Z]{2}"
},
"country_code_iso3": {
"type": "string",
"description": "Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.",
"pattern": "[A-Z]{3}"
},
"country_name": {
"type": "string",
"description": "The full name of the country that `number` is registered in."
},
"country_prefix": {
"type": "string",
"description": "The numeric prefix for the country that `number` is registered in."
},
"request_price": {
"type": "string",
"description": "The amount in EUR charged to your account."
},
"refund_price": {
"type": "string",
"description": "If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price."
},
"remaining_balance": {
"type": "string",
"description": "Your account balance in EUR after this request."
},
"current_carrier": {
"$ref": "#/$defs/niCurrentCarrierProperties"
},
"original_carrier": {
"$ref": "#/$defs/niInitialCarrierProperties"
},
"ported": {
"type": [
"string",
"null"
],
"description": "If the user has changed carrier for `number`. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.",
"enum": [
"unknown",
"ported",
"not_ported",
"assumed_not_ported",
"assumed_ported",
"null"
]
},
"roaming": {
"$ref": "#/$defs/niRoaming"
},
"caller_identity": {
"$ref": "#/$defs/niCallerIdentity"
},
"lookup_outcome": {
"type": "integer",
"description": "Shows if all information about a phone number has been returned. Possible values:\n\nCode | Text\n--- | ---\n0 | Success\n1 | Partial success - some fields populated\n2 | Failed\n",
"enum": [
0,
1,
2
]
},
"lookup_outcome_message": {
"type": "string",
"description": "Shows if all information about a phone number has been returned."
},
"valid_number": {
"type": "string",
"description": "Does `number` exist. `unknown` means the number could not be validated. `valid` means the number is valid. `not_valid` means the number is not valid. `inferred_not_valid` means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only.",
"enum": [
"unknown",
"valid",
"not_valid",
"inferred",
"inferred_not_valid"
]
},
"reachable": {
"type": [
"string",
"null"
],
"description": "Can you call `number` now. This is applicable to mobile numbers only.",
"enum": [
"unknown",
"reachable",
"undeliverable",
"absent",
"bad_number",
"blacklisted",
"null"
]
},
"real_time_data": {
"$ref": "#/$defs/niRealtimeData"
}
},
"required": [
"status",
"status_message",
"request_id",
"international_format_number",
"national_format_number",
"country_code",
"country_code_iso3",
"country_name",
"country_prefix"
],
"$defs": {
"niCallerIdentity": {
"type": "object",
"description": "Information about the network `number` is currently connected to.",
"properties": {
"caller_type": {
"type": "string",
"description": "The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.",
"enum": [
"business",
"consumer",
"unknown"
]
},
"caller_name": {
"type": "string",
"description": "Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request."
},
"first_name": {
"type": "string",
"description": "First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request. `unknown` if this information is not available."
},
"last_name": {
"type": "string",
"description": "Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request. `unknown` if this information is not available."
}
}
},
"niCurrentCarrierProperties": {
"type": [
"object",
"null"
],
"x-nexmo-developer-collection-description-shown": true,
"description": "Information about the network `number` is currently connected to. While in some cases and regions it may return information for non-mobile numbers, this field is supported only for mobile numbers.",
"properties": {
"network_code": {
"type": [
"string",
"null"
],
"description": "The [https://en.wikipedia.org/wiki/Mobile_country_code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier`number` is associated with. Unreal numbers are marked as`null` and the request is rejected altogether if the number is impossible according to the [E.164](https://en.wikipedia.org/wiki/E.164) guidelines."
},
"name": {
"type": [
"string",
"null"
],
"description": "The full name of the carrier that `number` is associated with."
},
"country": {
"type": [
"string",
"null"
],
"description": "The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format."
},
"network_type": {
"type": [
"string",
"null"
],
"description": "The type of network that `number` is associated with.",
"enum": [
"mobile",
"landline",
"landline_premium",
"landline_tollfree",
"virtual",
"unknown",
"pager",
"null"
]
}
}
},
"niInitialCarrierProperties": {
"type": [
"object",
"null"
],
"x-nexmo-developer-collection-description-shown": true,
"description": "Information about the network `number` was initially connected to.",
"properties": {
"network_code": {
"type": [
"string",
"null"
],
"description": "The [https://en.wikipedia.org/wiki/Mobile_country_code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier`number` is associated with. Unreal numbers are marked as`null` and the request is rejected altogether if the number is impossible according to the [E.164](https://en.wikipedia.org/wiki/E.164) guidelines."
},
"name": {
"type": [
"string",
"null"
],
"description": "The full name of the carrier that `number` is associated with."
},
"country": {
"type": [
"string",
"null"
],
"description": "The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format."
},
"network_type": {
"type": [
"string",
"null"
],
"description": "The type of network that `number` is associated with.",
"enum": [
"mobile",
"landline",
"landline_premium",
"landline_tollfree",
"virtual",
"unknown",
"pager",
"null"
]
}
}
},
"niRealtimeData": {
"type": [
"object",
"null"
],
"description": "[This parameter is deprecated] Real time data about the `number`",
"properties": {
"active_status": {
"type": "string",
"description": "[This parameter is deprecated. If requested it returns always inactive]. Whether the end-user's phone number is assigned to an operator's network. Can be active, inactive or null."
},
"handset_status": {
"type": "string",
"description": "[This parameter is deprecated. If requested it returns always off]. Whether the end-user's handset is reachable. Can be on if reachable or off if not reachable."
}
}
},
"niRoaming": {
"type": [
"object",
"null"
],
"description": "Information about the roaming status for `number`. This is applicable to mobile numbers only. If unknown, this may return a string of `unknown` instead of an object.",
"properties": {
"status": {
"type": "string",
"description": "Is `number` outside its home carrier network.",
"enum": [
"roaming",
"not_roaming"
]
},
"roaming_country_code": {
"type": "string",
"description": "If `number` is `roaming`, this is the [code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country `number` is roaming in."
},
"roaming_network_code": {
"type": "string",
"description": "If `number` is `roaming`, this is the id of the carrier network `number` is roaming in."
},
"roaming_network_name": {
"type": "string",
"description": "If `number` is `roaming`, this is the name of the carrier network `number` is roaming in."
}
}
},
"niStandardAdvancedStatus": {
"type": "integer",
"enum": [
0,
1,
3,
4,
5,
9,
19,
43,
44,
45,
999
],
"description": "Code | Text\n-- | --\n0 | Success - request accepted for delivery by .\n1 | Busy - you have made more requests in the last second than are permitted by your account. Please retry.\n3 | Invalid - your request is incomplete and missing some mandatory parameters.\n4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled.\n5 | Internal Error - the format of the recipient address is not valid.\n9 | Partner quota exceeded - your account does not have sufficient credit to process this request.\n19 | Facility Not Allowed - your request makes use of a facility that is not enabled on your account.\n43, 44, 45 | Live mobile lookup not returned. Not all return parameters are available.\n999 | Request unparseable.\n"
}
}
}