Global Phone V3:Response

← Global Phone V3 Reference

A response is the result of a request. This consists of returned results codes, parsed phone elements, and appended geographic information.

Depending on the protocol used to make the request, the response will be in a certain protocol. Global Phone supports four possible response protocols: SOAP, JSON, XML, and REST.

Field Names

This is a list of the response field names and their protocol naming conventions.

Field Name	Level	SOAP/JSON/XML
Version	Request	Version
Transmission Reference	Request	TransmissionReference
Transmission Results	Request	TransmissionResults
Total Records	Request	TotalRecords
Record ID	Record	RecordID
Results	Record	Results
Phone Number	Record	PhoneNumber
Phone International Prefix	Record	PhoneInternationalPrefix
Phone Country Dialing Code	Record	PhoneCountryDialingCode
Phone Nation Prefix	Record	PhoneNationPrefix
Phone National Destination Code	Record	PhoneNationalDestinationCode
Phone Subscriber Number	Record	PhoneSubscriberNumber
Locality	Record	Locality
Administrative Area	Record	AdministrativeArea
Country Name	Record	CountryName
DST	Record	DST
UTC	Record	UTC
Language	Record	Language
Latitude	Record	Latitude
Longitude	Record	Longitude

Response Elements

The following elements are the basic options for each request. These apply to the entire response, not the individual records.

Version

This is a string value that is the current revision number of Global Phone.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Version
JSON	“Version”:”string”
XML	<Version>string</Version>

TransmissionReference

This is a string value that serves as a unique identifier for this set of records. It is returned as sent by the Request Array, allowing you to match the Response to the Request.

Protocol	Syntax
SOAP	string = RespGlobalPhone.TransmissionReference
JSON	“TransmissionReference”:”string”
XML	<TransmissionReference>string</TransmissionReference>

TransmissionResults

This is a string value that lists error codes from any errors caused by the most recent request as a whole.

For a complete list of error codes, see Global Phone Result Codes.

Protocol	Syntax
SOAP	string = RespGlobalPhone.TransmissionResults
JSON	“TransmissionResults”:”string”
XML	<TransmissionResults>string</TransmissionResults>

TotalRecords

This is a string value that is the total number of records returned with the response.

Protocol	Syntax
SOAP	string = RespGlobalPhone.TotalRecords
JSON	“TotalRecords”:”string”
XML	<TotalRecords>string</TotalRecords>

Response Record Elements

SOAP, XML, and XFORMS Web Service’s Response Arrays will contain two elements called Records and ResponseRecord. JSON will only contain the Records element.

Protocol	Definition
SOAP	This element is an array of object variables of the type ResponseRecord.
JSON	Each phone number will be contained within [{}] under the Records element.
XML	There will be one ResponseRecord element per phone number being submitted to the Web Service.

Each of the following elements are returned for each record in the Response Array.

RecordID

This is a string value that is a unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.RecordID
JSON	“RecordID”:”string”
XML	<RecordID>string</RecordID>

Results

This is a string value with comma delimited status, error codes, and change codes for the record.

For a complete list of codes, see Global Phone Result Codes.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.Results
JSON	“Results”:”string”
XML	<Results>string</Results>

PhoneNumber

This is a string value of the standardized phone number after a successful call to the service.

The phone number will return in varying formats depending on the inputs. If the inputted country and country of origin are the same the returned number will include the National Destination Code + Subscriber Number. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	RU	495-728-5802
+7 495-728-5802	RU	RU	495-728-5802
+1 495-728-5802	RU	RU	495-728-5802

If the inputted country and country of origin differ, the returned number will include a leading ‘+’ followed by the Country Code + National Destination Code + Subscriber Number. The leading ‘+’ represents the International Prefix that is required to dial a number outside of the caller’s country. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	US	+7 495-728-5802
+7 495-728-5802	RU	US	+7 495-728-5802
+1 495-728-5802	RU	US	+7 495-728-5802

If a country is entered and a country of origin is left blank or not passed in, the returned number will match the format of the inputted phone number. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	<blank>	495-728-5802
+7 495-728-5802	RU	<blank>	+7 495-728-5802
+1 495-728-5802	RU	<blank>	+7 495-728-5802

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneNumber
JSON	“PhoneNumber”:”string”
XML	<PhoneNumber>string</PhoneNumber>

PhoneInternationalPrefix

This is a string value that returns the international exit code needed to call a number outside of the dialing country.

If the input country and country of origin differ, this will return the digit(s) required to be dialed before the country code.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneInternationalPrefix
JSON	“PhoneInternationalPrefix”:”string”
XML	<PhoneInternationalPrefix>string</PhoneInternationalPrefix>

PhoneCountryDialingCode

This is a string that returns a digit, or combination of digits, known as the country dialing code.

This will return the digit(s) dialed after the international prefix.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneCountryDialingCode
JSON	“PhoneCountryDialingCode”:”string”
XML	<PhoneCountryDialingCode>string</PhoneCountryDialingCode>

PhoneNationPrefix

This is a string that returns a digit, or combination of digits, known as the national prefix.

The national prefix must be dialed before an area (city) code when calling a number within the same country but outside the numbering area.

For example (US phone number): 1-949-589-5200 where 1 is the national prefix.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneNationPrefix
JSON	“PhoneNationPrefix”:”string”
XML	<PhoneNationPrefix>string</PhoneNationPrefix>

PhoneNationalDestinationCode

This is a string that returns a digit, or combination of digits, known as the national destination code.

The national destination code that identifies a numbering area within a country (or group of countries) and/or network/services.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneNationalDestinationCode
JSON	“PhoneNationalDestinationCode”:”string”
XML	<PhoneNationalDestinationCode>string</PhoneNationalDestinationCode>

PhoneSubscriberNumber

This is string that returns the subscriber number associated with the phone number passed in.

The subscriber number contains significant leading digits that further define the local exchange area and/or service.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.PhoneSubscriberNumber
JSON	“PhoneSubscriberNumber”:”string”
XML	<PhoneSubscriberNumber>string</PhoneSubscriberNumber>

Locality

This is a string that returns the locality (city) associated with the phone number passed to the Lookup function.

Because of phone portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.Locality
JSON	“Locality”:”string”
XML	<Locality>string</Locality>

AdministrativeArea

This is a string that returns the administrative area associated with the inputted phone number.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.AdministrativeArea
JSON	“AdministrativeArea”:”string”
XML	<AdministrativeArea>string</AdministrativeArea>

CountryName

This is a string that returns the name of the country for the inputted phone number.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.CountryName
JSON	“CountryName”:”string”
XML	<CountryName>string</CountryName>

DST

This is a string that returns a ‘Y’ (for yes) or ‘N’ (for no) to distinguish whether the region of the inputted phone number observes daylight savings time.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.DST
JSON	“DST”:”string”
XML	<DST>string</DST>

UTC

This is a string that returns the universal time code for the time zone associated with the inputted phone number.

UTC returns the time zone specified with the format: +/- hh:mm.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.UTC
JSON	“UTC”:”string”
XML	<UTC>string</UTC>

Language

This is a string that returns the predominant language of the phone’s detected geographical location.

The field will return the written out form of the language name. For example: “French”.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.Language
JSON	“Language”:”string”
XML	<Language>string</Language>

Latitude

This is a string that returns the latitude of the geographically identifiable service area of the exchange.

Latitude is the geographic coordinate of the locale, city, municipality, or other geographically identifiable service area of the exchange measured in degrees north or south of the equator.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.Latitude
JSON	“Latitude”:”string”
XML	<Latitude>string</Latitude>

Longitude

This is a string that returns the longitude of the geographically identifiable service area of the exchange.

Longitude is the geographic coordinate of the locale, city, municipality, or other geographically identifiable service area of the exchange measured in degrees east or west of the Greenwich Meridian.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Protocol	Syntax
SOAP	string = RespGlobalPhone.Records.ResponseRecord.Longitude
JSON	“Longitude”:”string”
XML	<Longitude>string</Longitude>