Page tree
Skip to end of metadata
Go to start of metadata

Introduction

DOTS Name Validation 2 is an XML RESTful web service that provides information about a person's name. With DOTS Name Validation 2, users can validate names, verify name accuracy, fix unordered names and return gender information.

If you are an existing client and are using the previous version of this service then please click on the following link.

DOTS Name Validation


Integration

Integrating NV2 into your application should be easy and straightforward.  If you are using a common platform, Service Objects may already have sample code built that you can use:
https://www.serviceobjects.com/developers/sample-code

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example.  Email support@serviceobjects.com for more details.

Web Service Structure:

Web services are methods that integrate with other applications via the web and encapsulate tricky business logic.  Web services are too large of a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible.

NV2 is a public XML web service that supports SOAP, POST and GET operations, using RESTful paradigms or simple HTTP transport calls.

The host path or physical location of the web service is here:
https://trial.serviceobjects.com/NV2/api.svc

A test page for the web service can be found here:
https://trial.serviceobjects.com/nv2/ 

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
https://trial.serviceobjects.com/NV2/api.svc?wsdl

Important Notes!
1. This XML is the definition of the web service, meaning its inputs, outputs, operations, and the like.  Most likely, you will have another tool read this WSDL and make the operations available to you in your application.  Whenever your utilities or IDE asks for a WSDL path to AV3, you can provide this one.

2. SOAP is done via POST, only with special XML markup in the post-body.

Every web service has operations that it offers to subscribers – methods that do different work and return different output.  Examining the link above, you will notice several of these operations available, which are described in detail later on.

Code Snippets




Name Validation 2 C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/nv2/api.svc
NV2LibraryClient client = new NV2LibraryClient();
NameInfoResponse response = new NameInfoResponse();
response = client.ValidateName(name, licenseKey);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


Name Validation 2 Java Code Snippet
NV2Name result = null;
NV2Error error = null;
// Create soap request
NameValidation2Locator locator = new NameValidation2Locator();
// use ssl
locator.setDOTSNameValidation2EndpointAddress("http://trial.serviceobjects.com/nv2/api.svc/soap");
INV2Library nv2 = locator.getDOTSNameValidation2();
INV2LibraryStub soap = (INV2LibraryProxy)nv2;
soap.setTimeout(5000);// set timeout
result = soap.validateName(name, key);
error = result.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS Name Validation 2 Results	
}
//Process Errors
else{
	//DOTS Name Validation 2 Error Results	
}


Name Validation 2 PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/nv2/api.svc?wsdl";

$params['Name'] = $Name;
$params['LicenseKey'] = $LicenseKey;

$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$soapResponse= $soapClient->ValidateName($params);
$result= $soapResponse->ValidateNameResult->NameInfo;
if (!isset($result->Error)) {
	foreach($result $k=>$v) {
		echo $k . ", " . $v;
	}
} else {
	foreach($result->Error as $k=>$v) {
		echo $k . ", " . $v;
	}
}
?>


Name Validation 2 RoR Soap Code Snippets
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
					"Name" => @request.name,					
					"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@nv2response = :validate_name_response
		@nv2result = :validate_name_result
		@nv2info = :name_info
		@nv2error = :error

		#Set Primary and Backup URLs here as needed
		dotsNV2Primary = "http://trial.serviceobjects.com/nv2/api.svc?WSDL"
		dotsNV2Backup = "http://trial.serviceobjects.com/nv2/api.svc?WSDL"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(	wsdl: dotsNV2Primary )
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:validate_name, message: message).to_hash
			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(wsdl: dotsNV2Backup)
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:validate_name, message: message).to_hash
			processresults(response)

			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client
	end


Name Validation 2 Python Soap Code Snippets
	    mName =  Name.get()
    if mName is None or  mName == "":
        mName = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the primary and backup URLs as needed
    primaryURL = 'http://trial.serviceobjects.com/NV2/api.svc?wsdl'
    backupURL = 'http://trial.serviceobjects.com/NV2/api.svc?wsdl'

    #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.ValidateName(Name= mName, LicenseKey=mLicenseKey)
        #Handel response and check for errors

    #Tries the backup URL if the primary URL failed
    except:
        try:
            client = Client(backupURL)
            result = client.service.ValidateName(Name= mName, LicenseKey=mLicenseKey)
           #Handel response and check for errors

        #If the backup call failed then this will display an error to the screen
        except:
            Label(swin.window, text='Error').pack()
            print (result.NameInfo)


Name Validation 2 ColdFusion Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/NV2/api.svc?wsdl");							  
				outputs = wsresponse.validateName("#Name#", "#LicenseKey#");
				writedump(outputs.getError());
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/NV2/api.svc?wsdl");							  
					outputs = wsresponse.validateName("#Name#", "#LicenseKey#");
				}
			}
			catch(any Exception)	{
		  		 writeoutput("An Error Has Occured. Please Reload and try again");		  		 
		 		}
	    }
</cfscript>


Name Validation 2 VB Snippet
Try
    Dim ws As New NV2.NV2LibraryClient
    Dim response As NV2.NameInfoResponse

    response = ws.ValidateName(Name.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        ''Set the primary and backup service references as necessary
        Dim wsbackup As New NV2.NV2LibraryClient
        Dim response As NV2.NameInfoResponse
        response = wsbackup.ValidateName(Name.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try


Name Validation 2 Apex Code Snippet
wwwServiceobjectsCom.NameInfoResponse result;
try{
wwwServiceobjectsCom.soap client = new wwwServiceobjectsCom.soap();
result = client.ValidateName([Name],[LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.soap backupClient = new wwwServiceobjectsCom.soap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'http://trial.serviceobjects.com/NV2/api.svc/soap';
result = backupClient.ValidateName([Name],[LicenseKey]);
}


Name Validation 2 TSQL Code Snippet
SET @requestBody = '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<ValidateName xmlns="http://www.serviceobjects.com">'+
				   '<Name>' + @name + '</Name>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateName>'+
				   '</s:Body>'+
				   '</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://ws.serviceobjects.com/NV2/api.svc/soap', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/INV2Library/ValidateName"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://wsbackup.serviceobjects.com/NV2/api.svc/soap', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/INV2Library/ValidateName"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



Name Validation 2 C# Rest Code Snippet
string mainURL ="https://trial.serviceobjects.com/NV2/api.svc/NameInfo/" + name + "/" + licenseKey + "?format=json";

NameInfo result = null;
 
HttpWebRequest request = WebRequest.Create(mainURL ) as HttpWebRequest;
request.Timeout = 5000;//timeout for get operation
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
	if (response.StatusCode != HttpStatusCode.OK)
		throw new Exception(String.Format(
		"Server error (HTTP {0}: {1}).",
		response.StatusCode,
		response.StatusDescription));
	//parse response
	DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(NameInfo));
	object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
	result = objResponse as NameInfo;
//processing result
if (result.error == null)
{
	//process result
}
else
{
	//process error
}


Name Validation 2 Java Rest Code Snippet
NameInfoResponse.Error error = null;
NameInfoResponse.IPLocationInfo = null;
INV2LibraryProxy NV2Client = new INV2LibraryProxy();
NameInfoResponse result = NV2Client.validateName(name, licenseKey);
if (result != null) {
	error = result.error;
	info = result.nameInfo;
}
 
//Process Results
if (error == null) {
	//DOTS Name Validation 2		
}
 
//Process Errors
else{
}
	//DOTS Name Validation 2
}


Name Validation 2 PHP Rest Code Snippets
$URL = "https://trial.serviceobjects.com/NV2/api.svc/NameInfo/".urlencode($Name)."/"urlencode($LicenseKey)."?format=json";
	
// Get cURL resource
$curl = curl_init();
curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Name Validation 2'));
curl_setopt($curl, CURLOPT_TIMEOUT, 5); //timeout in seconds
// Send the request & save response to $resp
$resp = curl_exec($curl);
$jsonIterator = new RecursiveIteratorIterator(new RecursiveArrayIterator(json_decode($resp, TRUE)), RecursiveIteratorIterator::SELF_FIRST);
foreach ($jsonIterator as $key => $val) 
{
	if(is_array($val)) 
	{
		echo "Name Validation 2 Results";
	} 
	else 
	{ 
		echo "$key";
		echo "$val";
	}
}


Name Validation 2 RoR Rest Code Snippets
      #This sets the default timeout for HTTParty get operation.
      default_timeout = 10

      name = @request.name
      licensekey = @request.licensekey

      #Checks the users input and sets values 
      name = "" if @request.name == nil
      licensekey = "" if @request.licensekey == nil

     #Set Primary and Backup URLs as needed
      primaryURL = URI.encode("https://trial.serviceobjects.com/NV2/api.svc/NameInfo?Name="+name+"&LicenseKey="+licensekey)
      backupURL = URI.encode("https://trial.serviceobjects.com//NV2/api.svc/NameInfo?Name="+name+"&LicenseKey="+licensekey)

      #These are set to access the hash that is returned
      @response = "NameInfoResponse"
      @info = "NameInfo"
      @error = "Error"

      #Begins the call the RESTful web service
      begin
        response = HTTParty.get(primaryURL, timeout: default_timeout)
        #processes the response to display to the screen
        
        #Passes the response from HTTParty and the hash key values to this method
        processresults(response)
       rescue StandardError => e
       		begin
       		#uses the backupURl in the event that the service encountered an error
       		response = HTTParty.get(backupURL, timeout: default_timeout)
          
          #processes the response returned from using the backupURL
           processresults(response)

          #If the backup url railed this will raise an error and display the 
          #error message returned from the HTTParty gem.
       		rescue StandardError => error
       		end
      end      
  end
	private 
      #processes HTTParty response and uses the resultshash and error hash to display
      #relevant info returned from the ServiceObjects web serivce
  def processresults(response)  
      #Processes Error Response from rest Client    
      #Processes Valid response from rest client  
     end


Name Validation 2 Python Rest Code Snippets
    mName =  Name.get()
    if mName is None or  mName == "":
         mName = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    primaryURL = 'http://trial.serviceobjects.com/NV2/api.svc/NameInfo?'
    backupURL = 'http://trial.serviceobjects.com/NV2/api.svc/NameInfo?'

    #The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
    inputs = {'Name': mName, 'LicenseKey': mLicenseKey}

    try:
        result = requests.get(primaryURL, params=inputs)
        #Parses the XML response from the service into a python dictionary type
        outputs = xmltodict.parse(result.content)
        #Handel response and check for errors

    except:
        try:
            result = requests.get(backupURL, params=inputs)
            #Parses the XML response from the service into a python dictionary type
            outputs = xmltodict.parse(result.content)
            #Handel response and check for errors

        #Prints an error message if the primary and backup urls failed
        except:
            Label(swin.window, text='Error').pack()
            print (result)


Name Validation 2 ColdFusion Rest Snippet
 <!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "http://trial.serviceobjects.com/NV2/api.svc/NameInfo?Name=#Name#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
	<cfcatch >
		<cftry>
			<cfset backupURL = "http://trial.serviceobjects.com/NV2/api.svc/NameInfo?Name=#Name#&LicenseKey=#LicenseKey#">
			<cfhttp url="#backupURL#" method="get" result="response">
			<cfset outputs = XmlParse(response.FileContent)>				
			<cfcatch type="any" name="error">
				<cfoutput>
					The Following Error Occured: "#error.Message#"
				</cfoutput>
			</cfcatch>
		</cftry>
	</cfcatch>
	</cftry>
</cfif>	


Name Validation 2 VB Rest Snippet
'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "http://trial.serviceobjects.com/NV2/api.svc/NameInfo?Name=" + WebUtility.UrlEncode(name) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey)
Dim backupurl As String = "http://trial.serviceobjects.com/NV2/api.svc/NameInfo?Name=" + WebUtility.UrlEncode(name) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey)
Dim wsresponse As New NV2Response.NameInfoResponse()
wsresponse = httpGet(primaryurl)

'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
If wsresponse Is Nothing OrElse (wsresponse.[Error].Type IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then

End If
If True Then
    wsresponse = httpGet(backupurl)
End If
If wsresponse.[Error].Type IsNot Nothing Then
    ProcessErrorResponse(wsresponse.[Error])
Else
    ProcessSuccessfulResponse(wsresponse)

End If


Name Validation 2 TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'http://ws.serviceobjects.com/nv2/api.svc/NameInfo?Name=' + @name + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'http://wsbackup.serviceobjects.com/nv2/api.svc/NameInfo?Name=' + @name + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using NVSample.DOTSNameValidation;
namespace NVSample
{
    public partial class _Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {   
            // Put user code to initialize the page here
            resultHeader.Visible = false;
            resultTable.Visible = false;
        }
        #region Web Form Designer generated code
        override protected void OnInit(EventArgs e)
        {
            //
            // CODEGEN: This call is required by the ASP.NET Web Form Designer.
            //
            InitializeComponent();
            base.OnInit(e);
        }
        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
        private void InitializeComponent()
        {
            this.Imagebutton1.Click += new System.Web.UI.ImageClickEventHandler(this.Imagebutton1_Click);
            this.Load += new System.EventHandler(this.Page_Load);
        }
        #endregion
        private void validateName(String name)
        {
            // addressValidation is a proxy used to simplify calls to the web-service 
            NV2LibraryClient client = new NV2LibraryClient();
            if (client != null)
            {
                NameInfoResponse resp = new NameInfoResponse();
                NameInfo res = new NameInfo();
                // Error is the data structure for the dreaded Error element. 
                NV2Error Error = new NV2Error();
                try
                {
                    // addressValidation is the proxy defined above
                    resp = client.ValidateName(nameInput.Text, licenseInput.Text);
                    res = resp.NameInfo;
                    /* Checking if the address.Error field contains data. 
                     * If address.Error contains data this means that 
                     * the either some information is missing or the 
                     * address has not been found.*/
                    if (resp.Error != null)
                    {
                        resultTable.Visible = false;
                        resultHeader.Visible = true;
                        resultHeader.Text = "Error: " + resp.Error.DescCode + " - " + resp.Error.Desc;
                        // displaying the error message
                    }
                    else
                    {
                        /* if the address.error does not contain any information,
                     * it remains uninitialized, hence on checking the 
                     * respective length an exception is raised. When such
                     * exception is raised this implies that a matching 
                     * valid address has been found.*/
                        resultHeader.Visible = true;
                        resultTable.Visible = true;
                        resultHeader.Text = "Valid Address Details";
                        /* setting visible the table to hold the valid address
                         * details*/
                        PrefixResult.Text = res.Prefix;
                        FirstNameResult.Text = res.FirstName;
                        MiddleNameResult.Text = res.MiddleName;
                        LastNameResult.Text = res.LastName;
                        SuffixResult.Text = res.Suffix;
                        FirstNameFoundResult.Text = res.FirstNameFound.ToString();
                        IsCommonFirstNameResult.Text = res.IsCommonFirstName.ToString();
                        FirstNameOriginResult.Text = res.FirstNameOrigin.ToString();
                        LastNameFoundResult.Text = res.LastNameFound.ToString();
                        IsCommonLastNameResult.Text = res.IsCommonLastName.ToString();
                        GenderResult.Text = res.Gender;
                        FirstNameAltResult.Text = res.FirstNameAlt;
                        MiddleNameAltResult.Text = res.MiddleNameAlt;
                        LastNameAltResult.Text = res.LastNameAlt;
                        FirstNameAltFoundResult.Text = res.FirstNameAltFound.ToString();
                        LastNameAltFoundResult.Text = res.LastNameAltFound.ToString();
                        GenderAltResult.Text = res.GenderAlt;
                        RelatedNamesResult.Text = res.RelatedNames;
                        VulgarityScoreResult.Text = res.VulgarityScore.ToString();
                        CelebrityScoreResult.Text = res.CelebrityScore.ToString();
                        BogusScoreResult.Text = res.BogusScore.ToString();
                        GarbageScoreResult.Text = res.GarbageScore.ToString();
                        FirstNameDictionaryScoreResult.Text = res.FirstNameDictionaryScore.ToString();
                        LastNameDictionaryScoreResult.Text = res.LastNameDictionaryScore.ToString();
                        IsNameGoodResult.Text = res.IsNameGood;
                        StatusResult.Text = res.Status;
                    }
                }
                catch
                {
                    resultTable.Visible = false;
                    resultHeader.Visible = true;
                    resultHeader.Text = "Error calling the NameInfo operation.";
                } // end try-catch
            }
            else
            {
                // debug str echo fastquote
                resultHeader.Text = "Fatal error: Could not create proxy to web-service methods.";
                resultTable.Visible = false;
            } // end if proxy != null
        } // end function validate address

        /// handle the click image button event
        /// ----------------------------------------------------------------------------
        /// private void Imagebutton1_Click(object sender, System.EventArgs e)
        /// ------------------------------------
        private void Imagebutton1_Click(object sender, System.Web.UI.ImageClickEventArgs e)
        {
            validateName(nameInput.Text);
        }
    }
}




NameInfo Example Request and Response


URL Request: 
https://trial.serviceobjects.com/NV2/api.svc/NameInfo/Michael%20J%20Wilson/licenseKey?format=json


Json Response
{"NameInfo":{"BestGuessName":null,"Prefix":"","FirstName":"Michael","MiddleName":"J","LastName":"Wilson","Suffix":"","FirstNameFound":true,"IsCommonFirstName":true,"FirstNameOrigin":"HEBREW","LastNameFound":true,"IsCommonLastName":true,"Gender":"Male","FirstNameAlt":"","MiddleNameAlt":"","LastNameAlt":"","FirstNameAltFound":false,"LastNameAltFound":false,"GenderAlt":"Unknown","RelatedNames":"Michael,Micheal,Miguel,Mike","VulgarityScore":0,"CelebrityScore":0,"BogusScore":0,"GarbageScore":0,"FirstNameDictionaryScore":0,"MiddleNameDictionaryScore":0,"LastNameDictionaryScore":0,"IsNameGood":"true","StatusCodes":"","Status":""},"Error":null}



XML Request: 
https://trial.serviceobjects.com/NV2/api.svc/NameInfo/Michael%20J%20Wilson/licenseKey?format=xml


XML Response
<NameInfoResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<NameInfo>
<BestGuessName i:nil="true"/>
<Prefix/>
<FirstName>Michael</FirstName>
<MiddleName>J</MiddleName>
<LastName>Wilson</LastName>
<Suffix/>
<FirstNameFound>true</FirstNameFound>
<IsCommonFirstName>true</IsCommonFirstName>
<FirstNameOrigin>HEBREW</FirstNameOrigin>
<LastNameFound>true</LastNameFound>
<IsCommonLastName>true</IsCommonLastName>
<Gender>Male</Gender>
<FirstNameAlt/>
<MiddleNameAlt/>
<LastNameAlt/>
<FirstNameAltFound>false</FirstNameAltFound>
<LastNameAltFound>false</LastNameAltFound>
<GenderAlt>Unknown</GenderAlt>
<RelatedNames>Michael,Micheal,Miguel,Mike</RelatedNames>
<VulgarityScore>0</VulgarityScore>
<CelebrityScore>0</CelebrityScore>
<BogusScore>0</BogusScore>
<GarbageScore>0</GarbageScore>
<FirstNameDictionaryScore>0</FirstNameDictionaryScore>
<MiddleNameDictionaryScore>0</MiddleNameDictionaryScore>
<LastNameDictionaryScore>0</LastNameDictionaryScore>
<IsNameGood>true</IsNameGood>
<StatusCodes/>
<Status/>
</NameInfo>
<Error i:nil="true"/>
</NameInfoResponse>

List of Operations

NameInfoV2 (Recommended Operation) - This operation classifies's, validates and parses names in real-time.

NameInfo - This operation validates and parses names in real-time. 

Operation Definitions

This section defines the input, output and behavior of the operations in DOTS Name Validation 2.

NameInfo

Uses the provided name to return information such as gender, name origin, and validity results.

NameInfo Inputs

Name

Type

Description

Name

String

The name to validate.

LicenseKey

String

Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/products/demographics-more/name-validation

NameInfo Outputs

If no errors are encountered a NameInfo element will be returned with the following information. If there is an error, an Error object will be returned (explained in next section).

Name

Type

Description

BestGuessNameNV2NameThe best guess name if a name was unable to be validated.

Prefix

String

The parsed out prefix (Mr, Mrs, etc)

FirstName

String

The parsed first name.

MiddleName

String

The parsed middle name.

LastName

String

The parsed last name

Suffix

String

The parsed suffix (Jr, Sr, II, etc)

FirstNameFound

Bool

Is the first name found in existing name tables (True / False)

IsCommonFirstName

Bool

Is the first name one of the most common first names in existing data (True / False)

FirstNameOrigin

String

National origin of the first name (Old-English, etc)

LastNameFound

Bool

Is the last name found in existing name tables (True / False)

IsCommonLastName

Bool

Is the last name one of the most common first names in existing data (True / False)

Gender

String

The likely gender of the name (Male, Female, Neutral)

FirstNameAlt

String

If more than one first name is found, the second first name (ex: John and Mary Smith)

MiddleNameAlt

String

If more than one middle name is found, the second middle name

LastNameAlt

String

If more than one last name is found, the second last name

FirstNameAltFound

Bool

Is the alternative first name found in existing name tables (True / False)

LastNameAltFound

Bool

Is the last name found in existing name tables (True / False)

GenderAlt

String

If more than one name is present, the gender of the second name

RelatedNames

String

Names related to the first name (Bill, Billy, Billie, etc)

VulgarityScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is a vulgar word or phrase. A score of 5 would be very likely and 0 would be not at all likely.

CelebrityScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is a celebrity. A score of 5 would be very likely and 0 would be not at all likely.

BogusScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is not a name but simply a word or phrase. A score of 5 would be very likely and 0 would be not at all likely.

GarbageScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is not a name but rather a series of random letters. A score of 5 would be very likely and 0 would be not at all likely.

FirstNameDictionaryScore

Int

A score ranging from 0 to 5 indicating the likelihood the given First name is not a name but a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

MiddleNameDictionaryScoreIntA score ranging from 0 to 5 indicating the likelihood the given Middle name is strictly a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

LastNameDictionaryScore

Int

A score ranging from 0 to 5 indicating the likelihood the given Last name is strictly a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

IsNameGoodStringAn analysis of whether or not the name is valid based on the results of the returned scores ("true", "false", or "unknown")
StatusCodesIntA code indicating penalties or extra information about a given name.

Status

String

A field offering more information about this name. Can contain messages offering suggestions for interpreting the name, etc.

NameInfoV2 (Recommended Operation)

Uses the provided name to return information such as classification, gender if a person, origin, similar names, related names and validity results.

NameInfoV2 Inputs

Name

Type

Description

Name

String

The name to validate.

OptionStringComma Separated List of Options. See available options below

LicenseKey

String

Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/products/demographics-more/name-validation

NameInfoV2 Outputs

If no errors are encountered a NameInfoV2 element will be returned with the following information. If there is an error, an Error object will be returned (explained in next section).

Name

Type

Description

BestGuessNameNV2NameThe best guess name if a name was unable to be validated.
NameInStringThe name as it was provided as input.
NameClassificationStringA determination made on the name whether it is believed to be a "Person","Business" or "Unknown"

Prefix

String

The parsed out prefix (Mr, Mrs, etc)

FirstName

String

The parsed first name.

MiddleName

String

The parsed middle name.

LastName

String

The parsed last name

Suffix

String

The parsed suffix (Jr, Sr, II, etc)

FirstNameFound

Bool

Is the first name found in existing name tables (True / False)

IsCommonFirstName

Bool

Is the first name one of the most common first names in existing data (True / False)

FirstNameOrigin

String

National origin of the first name (Old-English, etc)

FirstNameSimilarStringNames that phonetically sound the same as the given first name.

LastNameFound

Bool

Is the last name found in existing name tables (True / False)

IsCommonLastName

Bool

Is the last name one of the most common first names in existing data (True / False)

LastNameOriginStringNational origin of the last name (Old-English, etc)
LastNameSimilarStringNames that phonetically sound the same as the given last name.

Gender

String

The likely gender of the name (Male, Female, Neutral)

FirstNameAlt

String

If more than one first name is found, the second first name (ex: John and Mary Smith)

MiddleNameAlt

String

If more than one middle name is found, the second middle name

LastNameAlt

String

If more than one last name is found, the second last name

FirstNameAltFound

Bool

Is the alternative first name found in existing name tables (True / False)

LastNameAltFound

Bool

Is the last name found in existing name tables (True / False)

GenderAlt

String

If more than one name is present, the gender of the second name

RelatedNames

String

Names related to the first name (Bill, Billy, Billie, etc)

IsCorrectedNameboolIf the name has been corrected to produce a better result.
IsBusinessNameboolIf the provided name is a business name.
BusinessNameStringThe business name if the name provided was determined to be a business name.

VulgarityScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is a vulgar word or phrase. A score of 5 would be very likely and 0 would be not at all likely.

CelebrityScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is a celebrity. A score of 5 would be very likely and 0 would be not at all likely.

BogusScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is not a name but simply a word or phrase. A score of 5 would be very likely and 0 would be not at all likely.

GarbageScore

Int

A score ranging from 0 to 5 indicating the likelihood the given name is not a name but rather a series of random letters. A score of 5 would be very likely and 0 would be not at all likely.

FirstNameDictionaryScore

Int

A score ranging from 0 to 5 indicating the likelihood the given First name is not a name but a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

MiddleNameDictionaryScoreIntA score ranging from 0 to 5 indicating the likelihood the given Middle name is strictly a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

LastNameDictionaryScore

Int

A score ranging from 0 to 5 indicating the likelihood the given Last name is strictly a dictionary word. E.g., "Car" is strictly a dictionary word, but "Mark" is both a word and a name. A score of 5 would be very likely and 0 would be not at all likely.

OverallNameScoreIntA score ranging from 0 to 5 Indicating the quality of a given name. A score of 5 indicates the highest quality name, while a score of 0 indicates the lowest quality name. A name that is determined to be a business will be given a default score of 3.
IsNameGoodStringAn analysis of whether or not the name is valid based on the results of the returned scores ("true", "false", or "unknown")
StatusCodesIntA code indicating penalties or extra information about a given name.

Status

String

A field offering more information about this name. Can contain messages offering suggestions for interpreting the name, etc.

Options

Available options for ValidateNameV2. These options can be submitted as a comma separated list of values for the Option input.

OptionDescription
StrictIncrease penalties to meet stricter criteria. A provided name that is not a complete match in terms of First and Last Name found will be more heavily penalized
NoSwapDisables automatic name swap detection (Eg. Smith John) would not be corrected to John Smith.
NoBusinessDisables name classification checks and defaults to "Unknown" classification value.


NV2Name

A structure containing name information in the event a validated name could not be found

NameTypeDescription
PrefixStringThe parsed out prefix (Mr, Mrs, etc)
FirstNameStringThe parsed out first name.
MiddleNameStringThe parsed out middle name.
LastNameStringThe parsed out Last Name.
SuffixString

The parsed suffix (Jr, Sr, II, etc)

Errors

Anything that happens during a run of DOTS Name Validation 2 that causes it to be unable to finish its normal processing is an error. If an error occurs, something like the following will be the result instead of the normal output: 

Error

 <Type>Authorization</Type>
  <TypeCode>1</TypeCode>
  <Desc>Your license key does not work on this service.</Desc>
  <DescCode>8</DescCode>

There are four error types described below. 

Error Types


Type

TypeCode

Billable

Standard for all Gen2 Web Services

Authorization

1

No

Yes

User Input

2

Yes

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No


Error type 1: Authorization


These are standard to all Generation 2 DOTS Web Services.

DescCode

Description

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available.  Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service.

 

Error type 2: User Input


These errors occur as a result of bad input.  DOTS Name Validation 2 requires a name to be present in order for a proper validation to take place.

DescCode

Description

1

You must input a name.


Error type 3: Service Objects Fatal


The Desc will always be the same and the DescCode has no meaning.  This is standard to all Generation 2 DOTS Web Services.  This is a rare error that signals either a bug in the DOTS Name Validation 2 service or a Network/Connectivity issue.

DescCode

Description

1

Unhandled error.  Please contact Service Objects.


Error type 4: Domain Specific


Domain specific errors represent the normal errors seen in Service Objects services.  For example, if the user is looking for an address in DOTS Address Validation and the address does not exist, a valid domain specific error is "Address not found." 

DescCode

Description

1

An issue occurred during name parsing.

Conclusion



Other technical questions or concerns can be directed to 
support@serviceobjects.com. 

If you are interested in purchasing DOTS Name Validation 2, please contact 
sales@serviceobjects.com. We welcome your feedback! 

  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels