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
NV2Client = new NV2LibraryClient("DOTSNameValidation2Primary");
NV2Client.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
response = NV2Client.ValidateNameV2(name, option, licenseKey);
//NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
if (response == null || (response.Error != null && response.Error.TypeCode == "3"))
{
	//Call Backup Endpoint
}
return response;


Name Validation 2 Java Code Snippet
NameInfoV2Response  NV2Response = null;
NV2Error error= null;
String name = request.getParameter("iName");
String option = request.getParameter("iOption");
String licenseKey = request.getParameter("iKey");
			
NameValidation2Locator locator = new NameValidation2Locator();

locator.setEndpointAddress("soap", "http://trial.serviceobjects.com/NV2/api.svc/soap");

INV2Library soap = locator.getsoap();

try{
	NV2Response = soap.validateNameV2(name, option, licenseKey);
	
	error = NV2Response.getError();
	if(error !=null && error.getTypeCode() == "3")
	{
		throw new Exception();	
	}
	}
catch
{
	//call backup endpoint
}


Name Validation 2 PHP Code Snippets
<?php

// Only make Soap request or show the results table if the form was submitted.
if (($Action)=="Submit") {

// Invoke the operation
	$SoapResponse =
		$soapClient->ValidateNameV2(array(
		"Name" => $Name,
		"Option" => $Option,
		"LicenseKey" => $LicenseKey));

	//Store result node in a more convenient variable
	$ResultNode = $SoapResponse->ValidateNameV2Result;

	?>


Name Validation 2 RoR Soap Code Snippets
#Implemented to make the code more readable when accessing the hash     
@nv2response = :validate_name_v2_response
@nv2result = :validate_name_v2_result
@nv2info = :name_info_v2
@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,
              element_form_default: :qualified,
              convert_request_keys_to: :camelcase
             )
  #Calls the operation with given inptus and converts response to a hash.
  response = client.call(:validate_name_v2, 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,
                  element_form_default: :qualified,
                  convert_request_keys_to: :camelcase
                 )
  #Sets the response to the backclient call to the operation and converts response to a hash.
  response = backupclient.call(:validate_name_v2, message: message).to_hash
  processresults(response)

  #If backup url failed, this will display the error received from the server
  rescue Savon::Error =>error
    @status = error
    @displaydata = {"error" => "A Big Error Occured"}
  end
end


Name Validation 2 Python Soap Code Snippets
#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.ValidateNameV2(Name= mName, Option=mOption, LicenseKey=mLicenseKey)
    #Loops through either the error result or proper result and displays values to the screen.
    if hasattr(result, 'Error'):
        for value in result.Error:
            Label(swin.window, text=str(value[0]) + " : " + str(value[1]) if str(value[1]) else str(value[0])+": None").pack()

    else:
        #Prints all the values in a successful response except for BestGuessName
        for value in result.NameInfoV2:
            if str(value[0]) != 'BestGuessName':
                Label(swin.window, text=(str(value[0]) + ":  " + str(value[1]) if (str(value[1]) != "None") else str(value[0]) + " : None")).pack()

        if str(result.NameInfoV2.BestGuessName) != "None":
                Label(swin.window, font ='bold', text="Best Guess Name").pack()
                for value in result.NameInfoV2.BestGuessName:
                    Label(swin.window, text=str(value[0]) + ":  " + str(value[1]) if (str(value[1]) != "None") else str(value[0]) + " : None").pack()

#Tries the backup URL if the primary URL failed
except:
    try:
        client = Client(backupURL)
        result = client.service.ValidateNameV2(Name= mName, Option=mOption, LicenseKey=mLicenseKey)
        #Loops through either the error result or proper result and displays values to the screen.
        if hasattr(result, 'Error'):
            for value in result.Error:
                Label(swin.window, text=str(value[0]) + " : " + str(value[1]) if str(value[1]) else str(value[0])+": None").pack()


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.validateNameV2("#Name#", "#Option#", "#LicenseKey#");
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/NV2/api.svc?wsdl");							  
					outputs = wsresponse.validateNameV2("#Name#", "#Option#", "#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 NV2ServiceReference.NV2LibraryClient
    Dim response As NV2ServiceReference.NameInfoV2Response


    response = ws.ValidateNameV2(Name.Text, Opt.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 NV2ServiceReference.NV2LibraryClient
        Dim response As NV2ServiceReference.NameInfoV2Response

        response = wsbackup.ValidateNameV2(Name.Text, Opt.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.NameInfoV2Response result;
try{
wwwServiceobjectsCom.soap client = new wwwServiceobjectsCom.soap();
result = client.ValidateNameV2([Name], [Option], [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.ValidateNameV2([Name], [Option], [LicenseKey]);
}


Name Validation 2 TSQL Code Snippet
SET @requestBody = '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<ValidateNameV2 xmlns="http://www.serviceobjects.com">'+
				   '<Name>' + @name + '</Name>'+
				   '<Option>' + @option + '</Option>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateNameV2>'+
				   '</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/ValidateNameV2"'
	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/ValidateNameV2"'
		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 primaryurl = "http://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/" + Uri.EscapeDataString(name) + " / " + Uri.EscapeDataString(option) + "/" + Uri.EscapeDataString(licensekey) + "?format=xml";
string backupurl = "http://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/" + Uri.EscapeDataString(name) + " / " + Uri.EscapeDataString(option) + "/" + Uri.EscapeDataString(licensekey) + "?format=xml";

NameInfoV2Response wsresponse = new NameInfoV2Response();
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 == null || (wsresponse.Error != null && wsresponse.Error.Type != null && wsresponse.Error.TypeCode == "3")) ;
{
    wsresponse = httpGet(backupurl);
}

if (wsresponse.Error != null)
{
    ProcessErrorResponse(wsresponse.Error);
}
else
{
    ProcessSuccessfulResponse(wsresponse);
}

NameInfoV2Response.Error error = null;

NameInfoV2Response.NameInfoV2 nameInfoV2 = null;

try {
String name = request.getParameter("iName");
String option = request.getParameter("iOption");
String licenseKey = request.getParameter("iKey");

NV2RestClient NV2Client = new NV2RestClient();
NameInfoV2Response result = NV2Client.NameInfoV2(name, option, licenseKey);
if (result != null) {
error = result.error;
nameInfoV2 = result.NameInfoV2;
}


Name Validation 2 PHP Rest Code Snippets
// variable cleanup before generating url
$Name = trim($Name);
$LicenseKey = trim($LicenseKey);

$URL = "http://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/".rawurlencode($Name)."/".rawurlencode($Option)."/".rawurlencode($LicenseKey)."?format=xml";

//use backup url once given purchased license key
$backupURL = "http://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/".rawurlencode($Name)."/".rawurlencode($Option)."/".rawurlencode($LicenseKey)."?format=xml";


// 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, 50); //timeout in seconds
// Send the request & save response to $resp
$resp = curl_exec($curl);

// Close request to clear up some resources
if($resp == false)
{
	echo "IN back up block";
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Name Validation 2'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	if($resp == false)
	{
		echo "<b> Both rest calls failed </b>";
		curl_close($curl);
		return;
	}



Name Validation 2 RoR Rest Code Snippets
primaryURL = URI.encode("http://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?Name=" + name + "&Option=" + option+ "&LicenseKey=" + licensekey)
backupURL = URI.encode("http://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?Name=" + name + "&Option=" + option+ "&LicenseKey=" + licensekey)

#These are set to access the hash that is returned
@nv2response ="NameInfoV2Response"
@nv2info = "NameInfoV2"
@nv2BestGuessName = "BestGuessName"
@nv2error = "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 returned from HTTParty and processes them depending on the results
  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
 			@status = error.message
 			@displaydata = {"Error" => "A Big Error Occured"}
 		end

end


Name Validation 2 Python Rest Code Snippets
primaryURL = 'http://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?'
backupURL = 'http://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?'

#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, 'Option':mOption, '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)
    #checks the output for Errors and displays the info accordingly
    if 'Error' in outputs['NameInfoV2Response']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['NameInfoV2Response']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        for key, value in outputs['NameInfoV2Response']['NameInfoV2'].iteritems():
            if key != 'BestGuessName':
                Label(swin.window, text=str(key) + " : " + str(value)).pack()

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)
        #checks the output for Errors and displays the info accordingly
        if 'Error' in outputs['NameInfoV2Response']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['NameInfoV2Response']['Error'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        else:
            for key, value in outputs['NameInfoV2Response']['NameInfoV2'].iteritems():
                if key != 'BestGuessName':
                    Label(swin.window, text=str(key) + " : " + str(value)).pack()


Name Validation 2 ColdFusion Rest Snippet
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "http://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?Name=#Name#&Option=#Option#&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/NameInfoV2?Name=#Name#&Option=#Option#&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/NameInfoV2/" + Uri.EscapeUriString(name) + "/" + Uri.EscapeUriString(opt) + "/" + Uri.EscapeUriString(licensekey) + "?format=xml"
Dim backupurl As String = "http://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/" + Uri.EscapeUriString(name) + "/" + Uri.EscapeUriString(opt) + "/" + Uri.EscapeUriString(licensekey) + "?format=xml"

Dim wsresponse As New NameInfoV2Response()
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] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
    wsresponse = httpGet(backupurl)
End If

If wsresponse.[Error] IsNot Nothing Then
    ProcessErrorResponse(wsresponse.[Error])
Else
    ProcessSuccessfulResponse(wsresponse)


Name Validation 2 TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'http://ws.serviceobjects.com/nv2/api.svc/NameInfoV2?Name=' + @name + '&Option=' + @option + '&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/NameInfoV2?Name=' + @name + '&Option=' + @option + '&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);
        }
    }
}




NameInfoV2 Example Request and Response


URL Request: 
 https://trial.serviceobjects.com/NV2/api.svc/NameInfoV2/Mike%20Wilson/%20/{LicenseKey}?format=json


Json Response
{"NameInfoV2":{"BestGuessName":null,"NameIn":"Mike Wilson","NameClassification":"Person","Prefix":"","FirstName":"Mike","MiddleName":"","LastName":"Wilson","Suffix":"","FirstNameFound":true,"IsCommonFirstName":true,"FirstNameOrigin":"HEBREW","FirstNameSimilar":"Mike,Myke,Mik,Maike,Meike,Mieke","LastNameFound":true,"IsCommonLastName":true,"LastNameOrigin":"CELTIC","LastNameSimilar":"Wilson,Willson,Walson,Woolson,Welson,Wilsen,Wolson,Wulsin,Wilsson,Wiilson,Walsen,Welsen,Wilsin,Wilzen,Wylson,Wilhsson,Willsone,Wilsan","Gender":"Male","FirstNameAlt":"","MiddleNameAlt":"","LastNameAlt":"","FirstNameAltFound":false,"LastNameAltFound":false,"GenderAlt":"Unknown","RelatedNames":"Michael,Micheal,Miguel,Mike","IsCorrectedName":false,"IsBusinessName":false,"BusinessName":"","VulgarityScore":0,"CelebrityScore":0,"BogusScore":0,"GarbageScore":0,"FirstNameDictionaryScore":0,"MiddleNameDictionaryScore":0,"LastNameDictionaryScore":1,"OverallNameScore":5,"IsNameGood":"true","StatusCodes":"","Status":""}}



XML Request: 
https://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?Name=Mike+Wilson&Option=&LicenseKey={YourKeyHere}


XML Response
<NameInfoV2Response xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<NameInfoV2>
<BestGuessName i:nil="true"/>
<NameIn>Mike Wilson</NameIn>
<NameClassification>Person</NameClassification>
<Prefix/>
<FirstName>Mike</FirstName>
<MiddleName/>
<LastName>Wilson</LastName>
<Suffix/>
<FirstNameFound>true</FirstNameFound>
<IsCommonFirstName>true</IsCommonFirstName>
<FirstNameOrigin>HEBREW</FirstNameOrigin>
<FirstNameSimilar>Mike,Myke,Mik,Maike,Meike,Mieke</FirstNameSimilar>
<LastNameFound>true</LastNameFound>
<IsCommonLastName>true</IsCommonLastName>
<LastNameOrigin>CELTIC</LastNameOrigin>
<LastNameSimilar>
Wilson,Willson,Walson,Woolson,Welson,Wilsen,Wolson,Wulsin,Wilsson,Wiilson,Walsen,Welsen,Wilsin,Wilzen,Wylson,Wilhsson,Willsone,Wilsan
</LastNameSimilar>
<Gender>Male</Gender>
<FirstNameAlt/>
<MiddleNameAlt/>
<LastNameAlt/>
<FirstNameAltFound>false</FirstNameAltFound>
<LastNameAltFound>false</LastNameAltFound>
<GenderAlt>Unknown</GenderAlt>
<RelatedNames>Michael,Micheal,Miguel,Mike</RelatedNames>
<IsCorrectedName>false</IsCorrectedName>
<IsBusinessName>false</IsBusinessName>
<BusinessName/>
<VulgarityScore>0</VulgarityScore>
<CelebrityScore>0</CelebrityScore>
<BogusScore>0</BogusScore>
<GarbageScore>0</GarbageScore>
<FirstNameDictionaryScore>0</FirstNameDictionaryScore>
<MiddleNameDictionaryScore>0</MiddleNameDictionaryScore>
<LastNameDictionaryScore>1</LastNameDictionaryScore>
<OverallNameScore>5</OverallNameScore>
<IsNameGood>true</IsNameGood>
<StatusCodes/>
<Status/>
</NameInfoV2>
</NameInfoV2Response>

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.

NameInfoV2 (Recommended Operation)


URL Format

https://trial.serviceobjects.com/nv2/api.svc/NameInfoV2?Name={Name}&Option={Option}&LicenseKey={LicenseKey}


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.


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)


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.


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.
KeepLocalCharactersWill return accented characters in the output of the name if they are submitted in the input.

Status Codes

OptionDescription
1Name was given in inverse order
2Name uses dictionary words unlikely to be names
3Disables name classification checks and defaults to "Unknown" classification value.
4Name unknown due to multiple penalties
5Severe penalty found
6No last name
7One or more names contained international symbols
8One or more names is of unknown origin
9The provided name is classified as a business
10The provided name was leet speak translated
11Part of name is abbreviated.


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