Phonematch web service C# example

The following C# code example enables you to easily get up and running with the Phonematch web service. Simply use the authentication credentials supplied to you on sign up which we have made available to you in the My Account section.

You will likely prefer to use one of of the available OAuth libraries to handle client authentication. The OAuth library used in the following example is listed separately.

Whilst our code examples demonstrate the breadth of our capabilities, all of our examples are created using demo data and do not contain real or live personal data relating to data subjects. 

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Net;
using System.Web.Script.Serialization;
using OAuth;
 
namespace TraceSmart.Api
{
    public class PhonematchService
    {
        // Your consumer key and secret as supplied by Tracesmart
        private const string ConsumerKey = "b8e601941ad09b9478ac76c25b3bb46e10b8bdad";
        private const string ConsumerSecret = "3065d6fa76t2da717bc5765388a8795a45245583";
 
        public void MakeTestRequest()
        {
            IDictionary<string, string> parameters = new Dictionary<string, string>
                {
                    { "landlineService"   , "A"},
                    { "mobileService"     , "A"},
                    { "forename"          , "Heather"},
                    { "middleName"        , "Jane"},
                    { "surname"           , "Russell"},
                    { "address1"          , "201 Julius Road"},
                    { "address2"          , "Bristol"},
                    { "address3"          , ""},
                    { "address4"          , ""},
                    { "address5"          , ""},
                    { "postcode"          , "BS7 8EU"},
                    { "requestReference"  , "My Unique Reference"},
                    { "ignoreNumbers"     , "07777111112"}
                };
            var response = new PhonematchService().MakeRequest(parameters);
            Debug.Write(response);
            var matches = response["matches"] as object[];
            Debug.WriteLine("Found " + matches.Length + "{0} possible matches");
            foreach (IDictionary<string, object> match in matches)
                Debug.WriteLine(match["name"]);
        }
 
        public IDictionary<string,object> MakeRequest(IDictionary<string, string> parameters)
        {
            var httpWebRequest = BuildRequest(parameters);
            try
            {
                using (var httpWebResponse = (HttpWebResponse)httpWebRequest.GetResponse())
                {
                    var jsonResponse = ReadResponseToText(httpWebResponse);
                    Debug.WriteLine("Received json from the server:");
                    Debug.WriteLine(jsonResponse);
                    return new JavaScriptSerializer().Deserialize<IDictionary<string, object>>(jsonResponse);
                }
            }
            catch (WebException ex)
            {
                throw new PhonematchServiceException(
                    ReadResponseToText(ex.Response) ?? ex.Message,ex
                );
            }
        }
 
        private string ReadResponseToText(WebResponse response)
        {
            if (response == null)
                return null;
            using (var responseStream = new StreamReader(response.GetResponseStream()))
            {
                return responseStream.ReadToEnd();
            }
        }
 
        private HttpWebRequest BuildRequest(IDictionary<string, string> parameters)
        {
            // This is a live API, please contact us if you need to perform load, volume or security testing
            var rawRequestUrl = new Uri(
                "https://api.tracesmart.co.uk/phonematch/v1/match" + ToQueryString(parameters)
            );
            string normalizedUrl;
            string requestParameters;
            var oAuth = new OAuthBase();
            var signature = oAuth.GenerateSignature(
                rawRequestUrl, ConsumerKey, ConsumerSecret, null, null,
                "POST", oAuth.GenerateTimeStamp(), oAuth.GenerateNonce(),
                OAuthBase.SignatureTypes.HMACSHA1, out normalizedUrl,
                out requestParameters
            );
            var requestUrl = new Uri(normalizedUrl);
            var httpRequest = (HttpWebRequest)System.Net.WebRequest.Create(requestUrl);
            httpRequest.Method = "POST";
            httpRequest.ContentType = "application/x-www-form-urlencoded";
            using (var requestStream = new StreamWriter(httpRequest.GetRequestStream()))
            {
                requestStream.Write(
                    requestParameters
                    + "&oauth_signature="
                    + OAuthBase.UrlEncode(signature)
                );
            }
 
            return httpRequest;
        }
 
        private string ToQueryString(IDictionary<string, string> parameters)
        {
            return "?" + string.Join(
                "&", new List<string>(parameters.Keys).ConvertAll(
                    key => string.Format(
                        "{0}={1}",
                        OAuthBase.UrlEncode(key),
                        OAuthBase.UrlEncode(parameters[key])
                    )
                ).ToArray()
            );
        }
    }
 
    public class PhonematchServiceException : Exception
    {
        public PhonematchServiceException(string message, Exception innerException)
            : base(message, innerException)
        {
        }
    }
}
 

An example of code that might make use of the previous class is listed below: 

using System;
using System.Configuration;
using System.Data;
using System.Linq;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Xml.Linq;
using TraceSmart.Api;
 
namespace Phonematch_CS
{
    public partial class _Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            Phonematch cPhonematch = new PhonematchService();
            cPhonematch.MakeTestRequest();
 
        }
    }
}
 

From this juncture you should refer to the higher level documentation which explains how to send a request.