openapi: 3.2.0 info: title: Vonage Standard API version: 1.2.1 contact: name: Vonage DevRel email: devrel@vonage.com url: https://developer.nexmo.com/ license: name: The MIT License (MIT) url: https://opensource.org/licenses/MIT termsOfService: https://www.nexmo.com/terms-of-use x-metaDescription: Find quick answers to questions about the Vonage Number Insight API in this reference guide. Learn more in Vonage's API documentation. x-metaTitle: Vonage Number Insight API Reference | Vonage API Documentation description: 'Operations tagged Standard across 2 of this provider''s published API definitions: vonage-number-insight-openapi.json, vonage-number-insight-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.nexmo.com/ni security: - basicAuth: [] tags: - name: Standard paths: /standard/{format}: parameters: - $ref: '#/components/parameters/format' get: operationId: getNumberInsightStandard summary: Standard Number Insight description: 'Provides standard number insight information about a number. Note that this endpoint also supports `POST` requests.' 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' tags: - Standard servers: - url: https://api.nexmo.com/ni components: parameters: 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 format: name: format in: path required: true description: The format of the response example: json schema: type: string enum: - json - xml 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}' schemas: niBasicStatus: type: integer enum: - 0 - 1 - 3 - 4 - 5 - 9 example: 0 description: 'Code | Text -- | -- 0 | Success - request accepted for delivery by . 1 | Busy - you have made more requests in the last second than are permitted by your account. Please retry. 3 | Invalid - your request is incomplete and missing some mandatory parameters. 4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled. 5 | Internal Error - the format of the recipient address is not valid. 9 | Partner quota exceeded - your account does not have sufficient credit to process this request. ' 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. xml: attribute: true example: '12345' name: type: - string - 'null' description: The full name of the carrier that `number` is associated with. xml: attribute: true example: Acme Inc country: type: - string - 'null' description: The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format. xml: attribute: true example: GB 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' xml: attribute: true example: mobile 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: allOf: - $ref: '#/components/schemas/niCurrentCarrierProperties' original_carrier: $ref: '#/components/schemas/niInitialCarrierProperties' ported: 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 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 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' 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. xml: attribute: true example: '12345' name: type: - string - 'null' description: The full name of the carrier that `number` is associated with. xml: attribute: true example: Acme Inc country: type: - string - 'null' description: The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format. xml: attribute: true example: GB 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' xml: attribute: true example: mobile 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: allOf: - $ref: '#/components/schemas/niCurrentCarrierProperties' original_carrier: $ref: '#/components/schemas/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' 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 securitySchemes: basicAuth: type: http scheme: basic externalDocs: url: https://developer.nexmo.com/api/number-insight x-sha1: 081f6d985e2e4a75586da1654fde880a96885405 x-refined-from: - vonage-number-insight-openapi.json - vonage-number-insight-openapi.yml x-errors: validation: description: The provided payload is invalid resolution: 'Modify your request to provide a valid payload. * Minimum 8 characters * Maximum 25 characters * Minimum 1 lower case character * Minimum 1 upper case character * Minimum 1 digit ' link: text: View API reference url: /api/account#createAPISecret delete-last-secret: description: You can not delete your only API secret resolution: Add another API secret before deleting this one