{ "openapi": "3.0.0", "servers": [ { "url": "https://api.nexmo.com/ni" } ], "info": { "title": "Number Insight API", "x-metaTitle": "Vonage Number Insight API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Number Insight API in this reference guide. Learn more in Vonage's API documentation.", "version": "1.2.1", "description": "The Number Insight API delivers real-time intelligence about the validity, reachability and roaming status of a phone number and tells you how to format the number correctly in your application. There are three levels of Number Insight API available: [Basic, Standard and Advanced](https://developer.nexmo.com/number-insight/technical-details#basic-standard-and-advanced-apis). The advanced API is available asynchronously as well as synchronously.\n

Effective February 4, 2027, Vonage will sunset Vonage Number Insights. To ensure uninterrupted support and to provide a more scalable and future-proof solution, we encourage you to migrate to our enhanced offering: Vonage Identity Insights API.

The Vonage Identity Insights API consolidates multiple phone number-related datasets into a single, flexible API, allowing you to request real-time information about a phone number and retrieve any combination of insights - such as number formatting, carrier details, SIM Swap and Subscriber Match - in one call.

Please review the Number Insights Transition Guide, which provides detailed guidance on API differences, required changes, and best practices for a smooth transition.

", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.nexmo.com/" }, "termsOfService": "https://www.nexmo.com/terms-of-use", "license": { "name": "The MIT License (MIT)", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "url": "https://developer.nexmo.com/api/number-insight", "x-sha1": "081f6d985e2e4a75586da1654fde880a96885405" }, "security": [ { "basicAuth": [] } ], "paths": { "/basic/{format}": { "parameters": [ { "$ref": "#/components/parameters/format" } ], "get": { "operationId": "getNumberInsightBasic", "summary": "Basic Number Insight", "description": "Provides [basic number insight](/number-insight/technical-details#basic-standard-and-advanced-apis) information about a number.\n\nNote that this endpoint also supports `POST` requests.\n", "parameters": [ { "$ref": "#/components/parameters/number" }, { "$ref": "#/components/parameters/country" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/niResponseJsonBasic" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseXmlBasic" } } } } } } }, "/standard/{format}": { "parameters": [ { "$ref": "#/components/parameters/format" } ], "get": { "operationId": "getNumberInsightStandard", "summary": "Standard Number Insight", "description": "Provides [standard number insight](/number-insight/technical-details#basic-standard-and-advanced-apis) information about a number.\n\nNote that this endpoint also supports `POST` requests.\n", "parameters": [ { "$ref": "#/components/parameters/number" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/cnam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/niResponseJsonStandard" } ] } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseXmlStandard" } } } } } } }, "/advanced/async/{format}": { "parameters": [ { "$ref": "#/components/parameters/format" } ], "get": { "operationId": "getNumberInsightAsync", "summary": "Advanced Number Insight (async)", "description": "Provides [advanced number insight](/number-insight/technical-details#basic-standard-and-advanced-apis) number information **asynchronously** using the URL specified in the `callback` parameter. recommends asynchronous use of the Number Insight Advanced API, to avoid timeouts.\n\nNote that this endpoint also supports `POST` requests.\n", "parameters": [ { "$ref": "#/components/parameters/callback" }, { "$ref": "#/components/parameters/number" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/cnam" }, { "$ref": "#/components/parameters/ip" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/niResponseAsync" } ] } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseAsync" } } } } } } }, "/advanced/{format}": { "parameters": [ { "$ref": "#/components/parameters/format" } ], "get": { "operationId": "getNumberInsightAdvanced", "summary": "Advanced Number Insight (sync)", "description": "Provides [advanced number insight](/number-insight/technical-details#basic-standard-and-advanced-apis) information about a number synchronously, in the same way that the basic and standard endpoints do.\n\nVonage recommends accessing the Advanced API **asynchronously** using the `/advanced/async` endpoint, to avoid timeouts.\n\nNote that this endpoint also supports `POST` requests.\n", "parameters": [ { "$ref": "#/components/parameters/real_time_data" }, { "$ref": "#/components/parameters/number" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/cnam" }, { "$ref": "#/components/parameters/ip" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/niResponseJsonAdvancedSync" }, { "$ref": "#/components/schemas/niResponseJsonAdvancedRoamingUnknown" } ] } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseXmlAdvanced" } } } } } } } }, "x-webhooks": { "asyncResponse": { "{$request.query.callback}": { "post": { "operationId": "asyncResponse", "summary": "Asynchronous response", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/niResponseJsonAdvancedAsync" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseXmlAdvanced" } } } }, "responses": { "200": { "description": "OK" } } } } }, "asyncResponseUnknownRoaming": { "{$request.query.callback}": { "post": { "operationId": "asyncCallbackRoamingUnknown", "summary": "Asynchronous response with Unknown Roaming", "description": "Contains the response to your Number Insight Advanced API request.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/niResponseJsonAdvancedRoamingUnknown" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/niResponseXmlAdvanced" } } } }, "responses": { "200": { "description": "OK" } } } } } }, "components": { "parameters": { "format": { "name": "format", "in": "path", "required": true, "description": "The format of the response", "example": "json", "schema": { "type": "string", "enum": [ "json", "xml" ] } }, "real_time_data": { "name": "real_time_data", "in": "query", "description": "[This parameter is deprecated] Real time data about the number. This is applicable to mobile numbers only.", "example": true, "required": false, "schema": { "type": "boolean" } }, "number": { "name": "number", "in": "query", "description": "A single phone number that you need insight about in national or international format.", "example": "447700900000", "required": true, "schema": { "type": "string", "pattern": "^[0-9-+\\(\\)\\s]*$" } }, "country": { "name": "country", "in": "query", "example": "GB", "description": "If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.", "schema": { "type": "string", "pattern": "[A-Z]{2}" } }, "cnam": { "name": "cnam", "in": "query", "example": true, "description": "Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This feature is available only for US numbers but not all US numbers are supported. It incurs an additional charge for US numbers regardless of whether any information is returned. For non-US numbers and for non-approved users, the CNAM response attributes are omitted and no additional charges are incurred.", "schema": { "type": "boolean", "default": false } }, "ip": { "name": "ip", "in": "query", "example": "123.0.0.255", "description": "This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers. ", "schema": { "type": "string" }, "deprecated": true }, "callback": { "name": "callback", "in": "query", "example": "https://example.com/callback", "description": "The callback URL", "required": true, "schema": { "type": "string", "format": "uriref" } } }, "schemas": { "niAsyncResponse": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } }, "niResponseAsync": { "description": "Async Response", "type": "object", "xml": { "name": "lookup" }, "properties": { "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40, "xml": { "name": "requestId" } }, "number": { "type": "string", "description": "The `number` in your request", "example": "447700900000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789", "xml": { "name": "remainingBalance" } }, "request_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.", "example": "0.01500000", "xml": { "name": "requestPrice" } }, "status": { "$ref": "#/components/schemas/niStandardAdvancedStatus" }, "error_text": { "type": "string", "description": "The status description of your request. Note: This field is equivalent to `status_message` field in the other endpoints", "example": "Success" } } }, "niResponseXmlBasic": { "type": "object", "description": "Basic", "xml": { "name": "format" }, "properties": { "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40, "xml": { "name": "request_id" } }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "local_number": { "type": "object", "description": "An object containing the `number` in your request in the format used by the country the number belongs to.", "properties": { "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.", "example": "GB", "pattern": "[A-Z]{2}", "xml": { "attribute": true } }, "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.", "example": "GBR", "pattern": "[A-Z]{3}", "xml": { "attribute": true } }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom", "xml": { "attribute": true } }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44", "xml": { "attribute": true } }, "number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000", "xml": { "x-text": true } } } }, "error": { "type": "object", "description": "The error code and status of your request", "properties": { "code": { "type": "string", "description": "The status code", "example": "0", "xml": { "attribute": true } }, "status_text": { "type": "string", "description": "The status description of your request.", "example": "Success", "xml": { "x-text": true } } } } } }, "niResponseXmlStandard": { "type": "object", "description": "Standard", "xml": { "name": "lookup" }, "properties": { "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40, "xml": { "name": "request_id" } }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "local_number": { "type": "object", "description": "An object containing the `number` in your request in the format used by the country the number belongs to.", "properties": { "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.", "example": "GB", "pattern": "[A-Z]{2}", "xml": { "attribute": true } }, "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.", "example": "GBR", "pattern": "[A-Z]{3}", "xml": { "attribute": true } }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom", "xml": { "attribute": true } }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44", "xml": { "attribute": true } }, "number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000", "xml": { "x-text": true } } } }, "error": { "type": "object", "description": "The error code and status of your request", "properties": { "code": { "type": "string", "description": "The status code", "example": "0", "xml": { "attribute": true } }, "status_text": { "type": "string", "description": "The status description of your request.", "example": "Success", "xml": { "x-text": true } } } }, "request_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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/niCurrentCarrierProperties" } ] }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "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", "properties": { "ported_message": { "type": "string", "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" ], "example": "not_ported", "xml": { "x-text": true } } } }, "caller_identity": { "type": "object", "x-nexmo-developer-collection-description-shown": true, "description": "Contains details of the number owner, if `cnam` was set to `true` in the request.", "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" ], "example": "consumer", "xml": { "attribute": true } }, "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.", "example": "John Smith", "xml": { "attribute": true } }, "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.", "example": "John", "xml": { "attribute": true } }, "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.", "example": "Smith", "xml": { "attribute": true } }, "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.", "example": "John Smith" }, "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.", "example": "Smith" }, "firs_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.", "example": "John" }, "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" ], "example": "consumer" } } } } }, "niResponseXmlAdvanced": { "type": "object", "description": "Advanced", "xml": { "name": "lookup" }, "properties": { "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40, "xml": { "name": "request_id" } }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "local_number": { "type": "object", "x-nexmo-developer-collection-description-shown": true, "description": "An object containing the `number` in your request in the format used by the country the number belongs to.", "properties": { "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.", "example": "GB", "pattern": "[A-Z]{2}", "xml": { "attribute": true } }, "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.", "example": "GBR", "pattern": "[A-Z]{3}", "xml": { "attribute": true } }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom", "xml": { "attribute": true } }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44", "xml": { "attribute": true } }, "number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000", "xml": { "x-text": true } } } }, "error": { "type": "object", "x-nexmo-developer-collection-description-shown": true, "description": "The error code and status of your request", "properties": { "code": { "type": "string", "description": "The status code", "example": "0", "xml": { "attribute": true } }, "status_text": { "type": "string", "description": "The status description of your request.", "example": "Success", "xml": { "x-text": true } } } }, "request_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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "$ref": "#/components/schemas/niCurrentCarrierProperties" }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "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.", "properties": { "ported_message": { "type": "string", "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" ], "example": "not_ported", "xml": { "x-text": true } } } }, "caller_identity": { "description": "Contains details of the number owner, if `cnam` was set to `true` in the request.", "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" ], "example": "consumer", "xml": { "attribute": true } }, "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.", "example": "John Smith", "xml": { "attribute": true } }, "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.", "example": "John", "xml": { "attribute": true } }, "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.", "example": "Smith", "xml": { "attribute": true } } } }, "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.", "example": "John Smith" }, "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.", "example": "Smith" }, "firs_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.", "example": "John" }, "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" ], "example": "consumer" }, "lookup_outcome": { "type": "object", "x-nexmo-developer-collection-description-shown": true, "description": "An object indicating whether all information about a phone number has been returned.", "properties": { "code": { "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 ], "example": 0, "xml": { "attribute": true } }, "lookup_outcome_message": { "type": "string", "description": "Shows if all information about a phone number has been returned.", "example": "Success", "xml": { "x-text": true } } } }, "reachable": { "nullable": true, "type": "string", "description": "Can you call `number` now. This is applicable to mobile numbers only.", "enum": [ "unknown", "reachable", "undeliverable", "absent", "bad_number", "blacklisted", "null" ], "example": "reachable" }, "roaming": { "$ref": "#/components/schemas/niRoaming" }, "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_not_valid" ], "example": "valid" }, "ip_warnings": { "nullable": true, "type": "string", "description": "This property is deprecated and can safely be ignored.", "example": "unknown" } } }, "niResponseJsonBasic": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/niBasicStatus" }, "status_message": { "type": "string", "description": "The status description of your request.", "example": "Success" }, "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40 }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "national_format_number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000" }, "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.", "example": "GB", "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.", "example": "GBR", "pattern": "[A-Z]{3}" }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom" }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44" } } }, "niResponseJsonStandard": { "description": "Standard Response", "allOf": [ { "$ref": "#/components/schemas/niResponseJsonBasic" }, { "type": "object", "properties": { "request_price": { "type": "string", "description": "The amount in EUR charged to your account.", "example": "0.04000000" }, "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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/niCurrentCarrierProperties" } ] }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "type": "string", "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" ], "example": "not_ported" }, "caller_identity": { "$ref": "#/components/schemas/niCallerIdentity" }, "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.", "example": "John Smith" }, "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.", "example": "Smith" }, "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.", "example": "John" }, "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" ], "example": "consumer" } } } ] }, "niResponseJsonAdvancedSync": { "description": "Advanced Response (sync)", "type": "object", "properties": { "status": { "$ref": "#/components/schemas/niStandardAdvancedStatus" }, "status_message": { "type": "string", "description": "The status description of your request.", "example": "Success" }, "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40 }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "national_format_number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000" }, "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.", "example": "GB", "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.", "example": "GBR", "pattern": "[A-Z]{3}" }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom" }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44" }, "request_price": { "type": "string", "description": "The amount in EUR charged to your account.", "example": "0.04000000" }, "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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "$ref": "#/components/schemas/niCurrentCarrierProperties" }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "type": "string", "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" ], "example": "not_ported" }, "roaming": { "$ref": "#/components/schemas/niRoaming" }, "caller_identity": { "$ref": "#/components/schemas/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 ], "example": 0 }, "lookup_outcome_message": { "type": "string", "description": "Shows if all information about a phone number has been returned.", "example": "Success" }, "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" ], "example": "valid" }, "reachable": { "type": "string", "nullable": true, "description": "Can you call `number` now. This is applicable to mobile numbers only.", "enum": [ "unknown", "reachable", "undeliverable", "absent", "bad_number", "blacklisted", "null" ], "example": "reachable" }, "real_time_data": { "$ref": "#/components/schemas/niRealtimeData" } }, "required": [ "status", "status_message", "request_id", "international_format_number", "national_format_number", "country_code", "country_code_iso3", "country_name", "country_prefix" ] }, "niResponseJsonAdvancedAsync": { "description": "Advanced Response (Async)", "type": "object", "properties": { "status": { "$ref": "#/components/schemas/niStandardAdvancedStatus" }, "status_message": { "type": "string", "description": "The status description of your request.", "example": "Success" }, "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40 }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "national_format_number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000" }, "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.", "example": "GB", "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.", "example": "GBR", "pattern": "[A-Z]{3}" }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom" }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44" }, "request_price": { "type": "string", "description": "The amount in EUR charged to your account.", "example": "0.04000000" }, "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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "$ref": "#/components/schemas/niCurrentCarrierProperties" }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "type": "string", "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" ], "example": "not_ported" }, "roaming": { "$ref": "#/components/schemas/niRoaming" }, "caller_identity": { "$ref": "#/components/schemas/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 ], "example": 0 }, "lookup_outcome_message": { "type": "string", "description": "Shows if all information about a phone number has been returned.", "example": "Success" }, "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" ], "example": "valid" }, "reachable": { "type": "string", "nullable": true, "description": "Can you call `number` now. This is applicable to mobile numbers only.", "enum": [ "unknown", "reachable", "undeliverable", "absent", "bad_number", "blacklisted", "null" ], "example": "reachable" } }, "required": [ "status", "status_message", "request_id", "international_format_number", "national_format_number", "country_code", "country_code_iso3", "country_name", "country_prefix" ] }, "niResponseJsonAdvancedRoamingUnknown": { "description": "Unknown Roaming", "type": "object", "properties": { "status": { "$ref": "#/components/schemas/niStandardAdvancedStatus" }, "status_message": { "type": "string", "description": "The status description of your request.", "example": "Success" }, "request_id": { "type": "string", "description": "The unique identifier for your request. This is a alphanumeric string up to 40 characters.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", "maxLength": 40 }, "international_format_number": { "type": "string", "description": "The `number` in your request in international format.", "example": "447700900000" }, "national_format_number": { "type": "string", "description": "The `number` in your request in the format used by the country the number belongs to.", "example": "07700 900000" }, "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.", "example": "GB", "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.", "example": "GBR", "pattern": "[A-Z]{3}" }, "country_name": { "type": "string", "description": "The full name of the country that `number` is registered in.", "example": "United Kingdom" }, "country_prefix": { "type": "string", "description": "The numeric prefix for the country that `number` is registered in.", "example": "44" }, "request_price": { "type": "string", "description": "The amount in EUR charged to your account.", "example": "0.04000000" }, "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.", "example": "0.01500000" }, "remaining_balance": { "type": "string", "description": "Your account balance in EUR after this request.", "example": "1.23456789" }, "current_carrier": { "$ref": "#/components/schemas/niCurrentCarrierProperties" }, "original_carrier": { "$ref": "#/components/schemas/niInitialCarrierProperties" }, "ported": { "nullable": true, "type": "string", "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" ], "example": "not_ported" }, "roaming": { "type": "string", "example": "unknown", "enum": [ "unknown" ] }, "caller_identity": { "$ref": "#/components/schemas/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 ], "example": 0 }, "lookup_outcome_message": { "type": "string", "description": "Shows if all information about a phone number has been returned.", "example": "Success" }, "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" ], "example": "valid" }, "reachable": { "type": "string", "nullable": true, "description": "Can you call `number` now. This is applicable to mobile numbers only.", "enum": [ "unknown", "reachable", "undeliverable", "absent", "bad_number", "blacklisted", "null" ], "example": "reachable" } }, "required": [ "status", "status_message", "request_id", "international_format_number", "national_format_number", "country_code", "country_code_iso3", "country_name", "country_prefix" ] }, "niCurrentCarrierProperties": { "type": "object", "nullable": true, "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": { "nullable": true, "type": "string", "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.", "xml": { "attribute": true }, "example": "12345" }, "name": { "nullable": true, "type": "string", "description": "The full name of the carrier that `number` is associated with.", "xml": { "attribute": true }, "example": "Acme Inc" }, "country": { "nullable": true, "type": "string", "description": "The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.", "xml": { "attribute": true }, "example": "GB" }, "network_type": { "nullable": true, "type": "string", "description": "The type of network that `number` is associated with.", "enum": [ "mobile", "landline", "landline_premium", "landline_tollfree", "virtual", "unknown", "pager", "null" ], "xml": { "attribute": true }, "example": "mobile" } } }, "niInitialCarrierProperties": { "type": "object", "nullable": true, "x-nexmo-developer-collection-description-shown": true, "description": "Information about the network `number` was initially connected to.", "properties": { "network_code": { "nullable": true, "type": "string", "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.", "xml": { "attribute": true }, "example": "12345" }, "name": { "nullable": true, "type": "string", "description": "The full name of the carrier that `number` is associated with.", "xml": { "attribute": true }, "example": "Acme Inc" }, "country": { "nullable": true, "type": "string", "description": "The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.", "xml": { "attribute": true }, "example": "GB" }, "network_type": { "nullable": true, "type": "string", "description": "The type of network that `number` is associated with.", "enum": [ "mobile", "landline", "landline_premium", "landline_tollfree", "virtual", "unknown", "pager", "null" ], "xml": { "attribute": true }, "example": "mobile" } } }, "niRoaming": { "type": "object", "nullable": true, "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" ], "example": "roaming", "xml": { "attribute": true } }, "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.", "example": "US", "xml": { "attribute": true } }, "roaming_network_code": { "type": "string", "description": "If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.", "example": "12345", "xml": { "attribute": true } }, "roaming_network_name": { "type": "string", "description": "If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.", "example": "Acme Inc", "xml": { "attribute": true } } } }, "niRealtimeData": { "type": "object", "nullable": true, "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.", "example": "inactive" }, "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.", "example": "off" } } }, "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" ], "example": "consumer" }, "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.", "example": "John Smith" }, "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.", "example": "John" }, "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.", "example": "Smith" } } }, "niBasicStatus": { "type": "integer", "enum": [ 0, 1, 3, 4, 5, 9 ], "example": 0, "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.\n" }, "niStandardAdvancedStatus": { "type": "integer", "example": 0, "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" } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } } }