Web Service Topic

Universal Web Service Documentation

Version: 2.0 Web Service Topic Page(s) I. Overview 2-3 II. Web Service Security 4-5 III. Web Service Function Summary 5 IV. Retrieving Vehicle by VIN 6-11 V. End of Term Value

VI. Description Analysis 11-13 VII. The Description Translation Table 14-15 VIII. Description Translation Table Maintenance 16-18 VIII. Web Service Messages 19-20 IX. Web Service Transaction Counting 21 Appendix ‘A’ – Vehicle Classes 22 Appendix ‘B’ – U.S. Used Car Valuation Schema 23-26 Appendix ‘C’ – Canadian Used Car Valuation Schema 27-31 Appendix ‘D’ – Power Sports Valuation Schema 32 Appendix ‘E’ – Truck Valuation Schema 33-34

Confidential Page 1 1/9/2018 Universal Web Service Documentation

Version: 2.0

Section I. Overview

This section will provide you with a brief overview of the universal web service and all the options that are available to you when your account is setup. Subsequent sections of this document will delve into the details of each web service function, but a quick reference of general capabilities should jumpstart your efforts in integrating with the Black Book web service.

First, the domain name used exclusively for web services at Black Book is www.BlackBookWS.com. This particular service was developed using the Microsoft .Net framework, so all functionality derives from the UniversalWS.asmx document or at: https://www.BlackBookWS.com/UniversalWS. asmx. If you clicked on the link then you should see a list of all functions included in the universal web service. By simply adding ?WSDL onto the end of the URL you can access the web service description language, so try accessing https://www.BlackBookWS.com/UniversalWS.asmx?WSDL.

We also provide a development WebService domain for use while you are in the development process. The URLs to use are as follows. Development servers do not require a Secured HTTP call: http://www.nationalautoresearch.com/WebServices/UniversalWS.asmx http://www.nationalautoresearch.com/WebServices/UniversalWS.asmx?WSDL

Now that we know where to access the web service let’s take a closer look at some of your account setup options. These topics fall into five categories; (1) data markets, (2) historical valuations, (3) data frequencies, (4) data types, and (5) valuation conditions.

Data Markets 1. United States used cars 2. Canadian used cars 3. United States power sports 4. Canadian power sports 5. US trucks

Historical Valuations This option can be turned on for your account to permit a historical date to be passed in for retrieving historical values. If this option is not turned on then the web service simply returns current values.

Version: 2.0 Section I. Overview (continued)

Data Frequencies 1. Daily (U.S. used cars only) 2. Weekly (U.S. used cars only) 3. Monthly (U.S. only) 4. Bi-weekly (Canadian used cars only) 5. All – can change a frequency code for web service calls to pull data based on any data publish frequency.

Data Types (can only be setup by a Black Book system administrator) Any combination of data types can be turned on when your account is setup. And it takes two minutes to change the settings later if other information is required.

1. All data types 2. Wholesale Values 3. Retail Values 4. Trade-in Values 5. Residual Values 6. Finance Advance Value 7. Extra Fields (i.e. transmission, tire size, GVW, fuel type, cylinders, HP, wheel base)

Valuation Conditions (can only be setup by a Black Book system administrator) Any combination of conditions can be turned on when your account is setup. The conditions have to correlate to the data types that were turned on. And it takes two minutes to change the settings later if other valuation conditions are required.

All Data Types and All Trade-in average Conditions Wholesale extra clean Trade-in rough Wholesale clean 12 month residual Wholesale average 24 month residual Wholesale rough 30 month residual Retail extra clean 36 month residual Retail clean 42 month residual Retail average 48 month residual Retail rough 60 month residual Trade-in clean 72 month residual

Version: 2.0 Section II. Web Service Security

Security for the universal web service can be accomplished leveraging one of two methods. The first method requires that you pass in a logon id and password that was assigned to you at account setup time. The second method searches each HTTPS header for the IP address(es) that you provided at account setup time. More details concerning each method will follow.

It is also important to note that Black Book utilizes SSL or Secure Socket Layer (digital certificates) to secure the data packets transmitted between servers. In the overview section of this document you will notice that all URLs included the HTTPS designation. This measure ensures the data is encrypted and alleviates any concerns that may arise over sending the logon id and password to the web service in the first security option outlined below.

Logon ID and Password Security

This method requires the authentication information to be passed into the web service by populating the soap header with the user credentials. The universal web service has a class called UserCredentials that can be instantiated and populated to gain access using this method. The sample C# code below assumes that a reference to the web service has been established and is called universalws.

// create web service object reference protected universalws.UniversalWS ws = new universalws.UniversalWS(); // create user credentials class protected universalws.UserCredentials uc = new universalws.UserCredentials(); … uc.userid = “johnsmith”; // load logon id uc.password = “smith123”; // load password uc.producttype = "W"; // load ‘W’ for web service uc.customer = “XXX1234” //customer identifier for segregating hit & valuation counts ws.UserCredentialsValue = uc; // load credentials into soap header

This is all the code that is required to handle security, so that the web service can identify the requesting source and return the requested XML.

Version: 2.0 Section II. Web Service Security (Continued)

IP Address Security

If you choose not to pass in the logon id and password then an IP address or IP address range can be provided at setup time, so that authentication can be done at the server level, not user level. When a web service request is received the IP address is extracted from the HTTPS header for use in authentication. And the administration system for the web service handles any number of IP addresses and ranges. To find out what your IP address is and how the web service will authenticate your server please go to the following URL: https://www.BlackBookWS.com/universalws.asmx/IPAddress

Section III. Web Service Function Summary

This table contains a summary listing of all the web service functions and a brief description. A more detailed overview of each function will be covered in subsequent sections of this document. The namespace for the universal web service is UniversalWS.

Overload Overload Function Name (Y/N) Parameter Function Description getVINValues Y History Date, Retrieve vehicle values by VIN UVC, Maturity Date, Miles per year getVehicleClasses N Retrieve vehicle classifications getIPAddress N Retrieve IP address for account setup getTranslationEntries N Retrieve entries from the translation table getTranslationEntry N Retrieve a single entry from the translation table addTranslationEntry N Add a new entry to the translation table setTranslationEntryStatus N Set an existing translation entry’s status to Active or Inactive changeTranslationEntry N Change an existing translation entry by id

Version: 2.0 Section IV. Retrieving Vehicle By VIN

A common method of retrieving vehicle values is to perform a VIN lookup. The VIN parameter is the key to retrieving the values and will accept three different formats of VIN number.

1. Full 17 character VIN number 2. First 10 characters of the VIN number 3. Positions 1-8 and 10 of the VIN number

It is important to remember that when performing a VIN lookup, there are many instances where the VIN will return multiple vehicles. These occurrences have nothing to do with the way Black Book has established the VIN database, but instead has to do with the manufacturer’s VIN structure. Basically, in some instances there are simply too many vehicles for the number of VIN positions, so the one-to-many situation occurs. It is most prevalent on trucks and import vehicles, but once again, each manufacturer controls it.

The function has several signatures, one of which follows:

public DataSet getVINValues( string sCountryCode, string sMarketCode, string sFrequencyCode, string sVIN, int iMileage, string sState, int iExtraCleanAddDeductAdj, int iCleanAddDeductAdj, int iAverageAddDeductAdj, int iRoughAddDeductAdj, bool bReturnMileage, bool bReturnAddDeducts, string sVehicleDescription, string sModelNumber, DateTime dHistoricalDate)

Example: ds = ws.getVINValues("U", "U", "W", "1FTZR1444", 0, "NT", 0, 0, 0, 0, true, true,”Ford Ranger Edge”,”R14”);

Section IV. Retrieving Vehicle By VIN (continued)

Version: 2.0 Here is a summary of the parameters to the getVINValues function and a brief description of each.

Parameter Type Description sCountryCode string “U”=United States, “C”=Canada If you submit an “A” or an empty string, the API will search the US database. If no vehicle is found, it will then search the Canadian database. sMarketCode string “U”=used cars, “P”=power sports, “T”=trucks If you submit an “A” or an empty string, the API will attempt to determine the correct market. sFrequencyCode string “W”=weekly, “D”=daily, “M”=monthly, “B”=bi-weekly. Ignored for power sports and trucks - they are always monthly. sVIN string Full 17 characters OR first 10 characters OR positions 1-8 and 10 sUVC string Optional parameter - Full 10 character UVC OR 3 character UVC (last 3 characters) iMileage int US vehicles – mileage Canadian vehicles – kilometers Power sports – this field is ignored sState string 2 characters US vehicles – state code Canadian vehicles – province code Leave Blank for National iExtraCleanAddDeductAdj int This field applies to used cars only. Amount to adjust the base value for the Extra Clean condition iCleanAddDeductAdj int This field applies to used cars only. Amount to adjust the base value for the Clean condition iAverageAddDeductAdj int This field does not apply to power sports vehicles. Amount to adjust the base value for the Average condition

Version: 2.0 Section IV. Retrieving Vehicle By VIN (continued) iRoughAddDeductAdj int This field does not apply to power sports vehicles. Amount to adjust the base value for the Rough condition. bReturnMileage boolean Applies to used cars only. See details below. bReturnAddDeducts Boolean Does not apply to power sports. See details below. sVehicleDescription string Your description of the vehicle, to aid in choosing the best vehicle match when the VIN returns more than one vehicle. For more information, click here. sModelNumber string The manufacturer’s model number, if known, to aid in choosing the best vehicle match when the VIN returns more than one vehicle. For more information, click here. dHistoricalDate DateTime Optional – see details below dMaturityDate DateTime Optional - Used to calculate end of term value. iMilesPerYear int Optional - Used to calculate mileage adjustment for residuals and end of term value. Also used to calculate the current mileage adjustment if the iMileage parameter is zero.

The function getVINValues returns a dataset, as follows: Dataset Name vehiclevalues Table Name values Data Element (See tables for each market in the Name(s) Appendices)

It is important to discuss four of the parameters in the getVINValues function call in more detail: sUVC

This optional parameter can be used to avoid retrieving multiple vehicles. The 10-character code uniquely identifies each vehicle. The full UVC code can be broken down as follows: 1. Year – 4 digits (i.e. 2004) 2. Make Code – 3 digits (i.e. 987 for Autocar) 3. UVC Code – 3 digits (i.e. 001 for WX-Series WX42 81"BBC Low COE Truck 4X2)

So in looking at the sample above the full UVC would be 2004987001 and would

Version: 2.0 Section IV. Retrieving Vehicle By VIN (continued) identify the 2004 Autocar WX-Series WX42 81"BBC Low COE Truck 4X2. If every time a vehicle is retrieved and the full UVC was saved in your database then subsequent vehicle retrievals would be expedited with a one-to-one UVC. You can submit the full 10-character UVC or just the last three characters to this function. If you submit a UVC, but it does not match any of the vehicles identified by the VIN, you may still retrieve multiple vehicles. In this case a warning will be returned in the soap header. Also, if you submit a VIN that does not match any vehicles, but you also submit a 10-character UVC that does match a vehicle, that vehicle will be returned with a warning in the soap header. It is important that you always check the return code after every function call. For more information see the section, “Web Service Messages”. bReturnMileage

This parameter signals the web service to return the mileage adjustments for the vehicle being retrieved. A sample mileage range XML element group is outlined below.

5 1 18000 525 625 725 0 575 E

If the mileage parameter is set to zero then all the mileage ranges and adjustments will be returned. If a mileage parameter greater than zero is passed in then only the one, matching mileage range will be returned. The sample XML group above illustrates what the one mileage range, 1 – 18,000 miles, would look like when returned. bReturnAddDeducts

This parameter signals the web service to return the add/deduct adjustments.

Important Note: There are add/deducts associated with some VIN numbers or what Black Book terms automatic add/deducts. For example, if there is an add/deduct for a particular engine and that engine is identified in the VIN then the data element in the add/deduct schema will be set to “Y”. This means that the add/deduct adjustment value has already been

Version: 2.0 Section IV. Retrieving Vehicle By VIN (continued) added to each value (wholesale, retail, etc.). Even when the bReturnAddDeducts parameter is set to false the web service will automatically apply the automatic add/deduct adjustments to all the vehicle values. It is very important that the developer not apply the add/deduct adjustments a second time, so the data element should always be checked for a “Y”.

A sample add/deduct XML element group is outlined below. 05 w/o Auto Trans 4009 -450 -450 -450 -450 N 400 350 325 300 275 250 200 150

There can be from zero to in excess of ten add/deducts per vehicle. dHistoricalDate (optional parameter)

If the ability to query historical values was turned on for your account by a Black Book systems administrator then a date in the past can be entered to retrieve historical values. All the same data elements are returned with the values set as of that date. The history database goes back to May of 1999 for US and Canadian used car, July of 2001 for US PowerSports, January of 2006 for Canadian PowerSports, November of 2001 for truck, and October of 1999 for CPI, so any effort to query before these dates will result in an error.

Valuation Adjustments

The mileage, state, and add/deduct parameters are used to apply adjustments to the vehicle valuations. In other words, if you set the mileage parameter to a value greater than zero, then Section IV. Retrieving Vehicle By VIN (continued)

Version: 2.0 the web service will apply mileage adjustments. If a state/province is entered other than National, the corresponding adjustment will be applied to the vehicles value. If the sState field is left blank the webservice will consider the state/province to be National and no regional adjustment will be applied.

If you know the add/deducts that apply to a vehicle, you can call getVINValues with the bReturnAddDeducts boolean set to true, then sum the applicable add/deduct values and call the getVINValues or getUVCValues function again, passing in the total adjustment for each condition and the web service will apply them.

Section V. End of Term Value

The Used Car Web Service will calculate an end of term value when you call getVINValues and pass in a maturity date that is in the future. The end of term value is calculated by interpolating a value based on the residual values of the vehicle. If the maturity date is not in the future, the end of term value will be the adjusted wholesale value without regional adjustments. Note also that residual values, and therefore end of term values, are only provided for the most recent 5 model years. The end of term value will be adjusted for mileage if you supply the expected number of miles per year that the vehicle will be driven.

Section VI. Description Analysis

Introduction When a call is made to the getVINValues() method, and more than one vehicle is returned, the web service makes an effort to determine the correct vehicle based on your vehicle description and model number. This process is called description analysis. The result of this analysis is expressed as a “DescriptionScore” for each vehicle. The vehicle with the highest value for this score is the most likely match. The vehicles will be arranged in the data table in descending order of the description score. Following is a summary of the description analysis process:

Translation First, your vehicle description is translated for optimal matching with the Black Book description. Here is how the translation is done:

1. Change the description to lower case 2. Replace special characters such as “/”, “-“, “+”,“*”, etc. with spaces 3. Remove extra spaces 4. Translate known abbreviations and synonyms to a common spelling using the translation table. See the section on the translation table here for more details. Section VI. Description Analysis (Continued)

Version: 2.0 Second, the Black Book description, made up of the Year, Make, Model, Series and Body Style are also translated in the same manner as described above. Note that the customer and generic translation table entries are not used when translating the Black Book description.

Word Matching After the descriptions have been translated, they are compared to determine the number of words in your description that match a word in the Black Book description. Only whole word matches are counted. For example, “chas” does not match “chassis” – that is why the translation step above is important. There is one exception to this rule: If your model number contains the Black Book model number, it is considered a match. Furthermore, if a word from the Black Book description is found in your model number, it is counted as a match. For example, if your model number is X14XLT, and the Black Book model number is X14, they are considered a match. Also, if the Black Book series is XLT, a second match is counted because XLT is found in your model number.

Description Score The description score is a sum of two numbers:

1. The total number of words matched (plus an additional matching word if your series description matches the series found in the Black Book description) multiplied by 1000 2. The overall percentage of words in the Black Book description (made up of Make, Model, Series, Style and Model Number) that are matched by your description and model number.

For example:

Given the following Black Book information: . Description: 2000 Ford Contour SE 4D Sedan . Model Number: P66 After translation the Black Book description is: ford contour se 4d sedan

And the following customer information: . Description: CONTOUR SE 4 DOOR SEDAN . Model Number: P66 After translation, the customer description is: contour se 4d sedan

The number of Black Book words is 6 (5 from the description and 1 in the model number) The number of customer words that match is 5 (contour, se, 4d, sedan, P66) The customer description matched on the series so 1 additional word is awarded The percentage of words matched is 100 (6/6) So the description score is (6 * 1000) + 100 = 6100

Section VI. Description Analysis (Continued)

Version: 2.0 Tie Breaker Sometimes, the highest score will be shared by more than one vehicle. In some cases, those vehicles may have the same UVC. If they have the same UVC, then the value of those vehicles will be the same, so there is no need to break the tie. However, if they have different UVC’s, the following logic is applied.

If your description contains the word “Base” or “Fleet”, it is assumed that the Black Book vehicle with the lowest MSRP (except a Work Truck) is the most likely match. So that vehicle is awarded one additional word and one additional matching word. For example, if the description score prior to the tie breaker was 2050, indicating 2 matching words and 50%, the adjusted score would be 3060, indicating 3 matching words and 60%.

Output When description analysis is done, several additional elements are added to the valuation data table. The most important is the “descriptionScore”, but several other elements are also included to help you understand how that score was determined for specific vehicles. Here is a list of all of the elements that are added:

Data Element Description Example descriptionScore The score assigned to the vehicle 6100 description and model number provided by the customer when compared to the Black Book description and model number for this vehicle bborgdesc The original Black Book description for 2000 Ford Contour SE 4D this vehicle - before the translation step. Sedan bbmoddesc The modified Black Book description for ford contour se 4d sedan this vehicle – after the translation step. custorgdesc The original customer description – as CONTOUR SE 4 DOOR passed into the getVINValues function in SEDAN the sVehicleDescription parameter. custmoddesc The modified customer description – after contour se 4d sedan the translation step custmodnumber The customer model number – as passed P66 into the getVINValues function in the sModelNumber parameter. matchingwords The list of words from the customer contour se 4d sedan P66 description and model number that matched words in the Black Book description and model number

Version: 2.0

Conclusion Please note that there will still be cases where all of the vehicles will receive the same score. This usually indicates a poor vehicle description, but it may also indicate that additional translations need to be added to the customer translation table.

Section VII. The Description Translation Table

The description translation table is used to translate Black Book and customer vehicle descriptions as part of the description analysis process described above. There are three types of entries in the description translation table as described below:

Entry Type Maintained by Description Universal Black Book Universal entries are always used whether Black Book descriptions or customer descriptions are being translated. Common Black Book Common entries are used for translating all customer descriptions, but not for translating Black Book descriptions. Customer Customer (you) Customer descriptions are only used for translating your descriptions.

The table below shows some sample translation table entries:

ID Type Market Year Make Model Find Replace Last Score Status Update 0 Universal chas chassis 1/1/2009 0 A 1 Universal w t work truck 1/1/2009 0 A 2 Common 4 door 4d 1/1/2009 0 A 3 Common Ltd limited 1/15/2009 0 I 4 Customer U Ford work ws 1/12/2009 2 A special 5 Customer P ext extra 1/20/2009 1 A 6 Customer P Yamaha ext exciter 1/20/2009 2 A 7 Customer T conv conversion 1/20/2009 1 A 8 Customer T Chevrolet C-series cbvr cabover 1/20/2009 3 A

First, let’s learn a little about each of the columns in the table.

1. The ID field is assigned by the system and identifies the entry. 2. You already know about the type field. See above. 3. The market field can be blank, which means that it applies to all markets, or it can be “U” for used cars, “P” for power sports or “T” for trucks.

Version: 2.0 Section VII. The Description Translation Table (Continued)

4. The year, make and model fields can be blank, to indicate that the entry can be used for all vehicles within the specified market. If any of these fields are populated, the entry will only be used for vehicles that match the values entered. The values should be valid Black Book spellings of the data, otherwise, the entries will never be used. 5. The find field is the word or phrase to be replaced. Note that the entry should not contain special characters, since the web service removes special characters before the translation is done. Notice ID # 1 in the table above. Black Book vehicle descriptions will usually contain “w/t” as an abbreviation for “work truck”. The “/” will be replaced with a space before the translation process begins, so this entry contains w space t in the find field. 6. The replace field should contain the value that should replace the word or phrase in the find field. 7. The date added and last update (not shown) fields are updated by the system when the record is added or changed. 8. The score field is calculated by the system and indicates how specific the entry is. It is simply a count of the number of these columns that are populated: year, make, model. Also, one is added to the score if the column is a Customer column. The purpose of the score is to determine which entry to use when two entries have the same value in the find field – the highest score wins. 9. The status field indicates “A” for active or “I” for inactive.

Here is how the translation table is used to translate a description for a specific vehicle:

1. First, entries that are for a different market are discarded. 2. Then, if any entries have the year, make or model field populated and the value does not match the Black Book year, make or model of the vehicle, those entries are discarded. 3. If any remaining entries have matching find fields (in other words, if the find field of one entry matches the find field of another entry), only the entry with the highest score is kept. 4. The remaining translation table entries are then processed in alphabetic order of the find field as follows: If the word or phrase in the find field is found in the description, it is replaced with the word or phrase in the replace field.

Version: 2.0 Section VIII. Description Translation Table Maintenance

The following functions facilitate the maintenance of the Customer entries in the Description Translation table.

Retrieving the Description Translation Table

Use the getTranslationEntries function to retrieve all or part of the translation table. The function signature is as follows:

public DataSet getTranslationEntries(string sType, string sStatus) Example: ds=ws.getTranslationEntries(“”,”A”);

The sType parameter should be blank for all, “U” for universal, “M” for common, or “C” for customer. The sStatus parameter should be blank for all, “A” for active or “I” for inactive. Similarly, if you know the id, you can get a single entry from the translation table by calling the getTranslationEntry function which has the following signature:

public DataSet getTranslationEntry(int id)

Here is the schema for the data returned for both functions.

Data element Description Id The ID of the entry Type “U” for universal, “M” for common or “C” for customer Market “U” for used cars, “P” for power sports, “T” for trucks Year Vehicle year or blank Make Vehicle make or blank Model Vehicle model or blank Find Word or phrase to find Replace Word or phrase to replace “find” with Lastupdate Date of last update to this entry Adddate Date this entry was first added Score The entry score Status “A” for active or “I” for inactive

Version: 2.0 Section VIII. Description Translation Table Maintenance (Continued)

Adding a new translation table entry

Use the addTranslationEntry function to add a new customer entry to the translation table. You cannot add a new universal or common entry: they are maintained by Black Book. The function signature is as follows:

public int addTranslationEntry( string sMarket, string sYear, string sMake, string sModel, string sFind, string sReplace)

Example: int iEntryID = ws.addTranslationEntry(“U”,”2000”,”Ford”,”F150”,”spc”,”special”);

The integer that is returned is the ID of the new entry. If an error occurred, the integer will be negative, and the message in the soap header will indicate the cause of the error. Warnings may also be returned in the header, so be sure to check the returncode.

Changing the status of a translation table entry

You cannot delete an entry from the translation table, but you can change it’s status to inactive. You can also later change it’s status back to active. Do not try to change the status of a universal or common entry, as they are maintained by Black Book. The function signature is as follows:

public boolean setTranslationEntryStatus( int ID, string sStatus)

Example: boolean bResult = ws.setTranslationEntryStatus(34,”I”);

The boolean that is returned will be true if the function successfully changed the status. Otherwise, it will be false.

Version: 2.0 Section VIII. Description Translation Table Maintenance (Continued)

Changing the values of a translation table entry

You can change the values of fields in the translation table entry if you have the id of the entry you want to change. The function signature is as follows:

public boolean changeTranslationEntry( int ID, string sMarket, string sYear, string sMake, string sModel, string sFind, string sReplace)

Example: boolean bResult = ws.changeTranslationEntry(36,”U”,””,””,””,”cv”,”convertible”);

The boolean that is returned will be true if the change was successful. Otherwise, it will be false;

Version: 2.0 Section IX. Web Service Messages The messages returned from the web service fall into two categories, errors and warnings. Errors are returned when data cannot be returned or the validity of the data is in question. Whereas, warnings simply communicate that an event occurred that you need to be aware of, but data was still returned.

The soap header will contain two data elements for messaging on every web service call, the return code and the return message. The code below that was written in C# illustrates how to access the soap header and the return code and return message.

string sCode = ws.UserCredentialsValue.returncode; string sMessage = ws.UserCredentialsValue.returnmessage;

The table below contains all valid error codes and messages.

Code Error Description 1 invalid logon id and password 2 invalid data frequency 3 error retrieving mileage 8 error retrieving add deducts 9 error retrieving Canadian mileage 10 error retrieving US mileage 11 error retrieving UVC values 12 error retrieving VIN values 14 database error 20 VIN not found 22 Error retrieving vehicle classifications 25 No access rights for trend analysis data 26 Invalid Market 27 Invalid Country 28 Invalid Country/Market combination 29 VIN not found for the requested date 70 The string cannot be empty 71 Special characters are not allowed 72 Translation table entry not found 73 Permission denied: Entry can only be changed by owner 74 Invalid year for this market 75 Invalid make for this market 76 Invalid model for this market 77 Duplicate entry found (replacement text may differ)

Version: 2.0 Section IX. Web Service Messages (continued)

The table below contains all valid warning codes and messages.

Code Warning Description 101 invalid VIN check digit 102 limited to 2 years of monthly trend analysis values 103 limited to 5 years of annual trend analysis values 104 invalid data type specified (defaults to profile) 105 invalid data frequency (annual or monthly - defaults to monthly) 106 vehicle found but historical values not found 107 state ignored when no country is provided - defaults to National 108 Invalid UVC (must be 3 or 10 digits) 109 UVC not found 110 VIN Not Found- accessed by UVC 111 Miles per year and/or maturity date has been passed in for PwrSports or MD/HD Truck

Version: 2.0

Section X. Web Service Transaction Counting

When the web service is called each transaction is counted using a unique identifier, so that the counts can be grouped by function call. Typically a transaction based business model will bill based on only those transaction where values or other proprietary information is returned.

For example, the web service counts all the calls to the getVehicleClasses function, but typically no billing occurs for these function calls. Whereas, when the getVINValues function is called and values are returned there is usually associated billing. The fact that the web service counts each function call separately and can report the volume back to customers makes the product very flexible from a business standpoint.

When your account is setup, a unique, secure web page will be setup for you, so you can view and monitor transactions on a real-time basis.

Version: 2.0

Appendix ‘A’ – Vehicle Classes

When a vehicle valuation dataset is returned from the web service a data element called Veh_class is included in the XML that is returned. The following tables show the possible values for each market.

Used Cars (U.S. and Canada) - The code retuned in the Veh_class data element correlate to the classification descriptions outlined in the table below.

Code Classification Description A Compact Car C Mid-Size Car E Full-Size Car F Luxury Car I Sports Car K Pickup N Mid-Size SUV P Full Size SUV R Cargo Van S Passenger Van X Crossover SUV

Power Sports (U.S. and Canada) – The full description is returned. Classification Description Jet Boats Off Road On/Off Road Scooter Snowmobile Street Utility Watercraft

Trucks – The full description is returned. Classification Description Heavy Duty Truck Medium Duty Truck Trailer

Version: 2.0

Appendix ‘B’ – U.S. Used Car Valuation Schema

Data Element Name Element Description country ‘U’ = United States frequency ‘D’ = Daily, ‘W’ = Weekly, ‘M’ = Monthly year 4 digit year make i.e. Ford model i.e. Expedition series i.e. XLT style i.e. 4D Utility vIN_year 10th position of VIN whole_xclean Adjusted Wholesale extra clean whole_clean Adjusted Wholesale clean whole_avg Adjusted Wholesale average whole_rough Adjusted Wholesale rough retail_xclean Adjusted Retail extra clean retail_clean Adjusted Retail clean retail_avg Adjusted Retail average retail_rough Adjusted Retail rough tradein_clean Adjusted Trade-in clean tradein_avg Adjusted Trade-in average tradein_rough Adjusted Trade-in rough finadv Adjusted Finance advance resid12 Adjusted 12 Month residual resid24 Adjusted 24 Month residual resid30 Adjusted 30 Month residual resid36 Adjusted 36 Month residual resid42 Adjusted 42 Month residual resid48 Adjusted 48 Month residual resid60 Adjusted 60 Month residual resid72 Adjusted 72 Month residual Return To Table of Contents

Version: 2.0

Appendix ‘B’ – US Valuation Schema (continued)

Data Element Name Element Description region2 Region 2 adjustment value region3 Region 3 adjustment value region4 Region 4 adjustment value region5 Region 5 adjustment value region6 Region 6 adjustment value group_number MSRP Manufacturer's suggested retail value ERT Equipped retail value mileage_category actualdate Date the values were published full_VIN Positions 1-8 and 10 of the VIN full_UVC 10 digits = year + make code + three digit UVC code UVC Three digit UVC model_number Manufacturer model number veh_class Vehicle class code wheel_base i.e. 108.5 base_HP i.e. 125 @ 6000 taxable_HP i.e.. 17.1 GVW i.e. 2601 cylinders i.e. 8 fuel_type i.e. Gas tire_size i.e. 185/65R14 engine i.e. 3.8L V6 EFI transmission i.e. A = automatic drivetrain i.e. FWD base_whole_xclean Wholesale Extra Clean value before any adjustments base_whole_clean Wholesale Clean value before any adjustments base_whole_avg Wholesale Average value before any adjustments base_whole_rough Wholesale Rough value before any adjustments mileage_adj_whole_xclean Mileage adjustment amount for wholesale extra clean mileage_adj_whole_clean Mileage adjustment amount for wholesale clean mileage_adj_whole_avg Mileage adjustment amount for wholesale average Mileage_adj_whole_rough Mileage adjustment amount for wholesale rough ad_adj_whole_xclean Automatic add/Deduct adjustment amount for wholesale extra clean Return To Table of Contents

Version: 2.0

Data Element Name Element Description ad_adj_whole_clean Automatic add/Deduct adjustment amount for wholesale clean ad_adj_whole_avg Automatic add/Deduct adjustment amount for wholesale average ad_adj_whole_rough Automatic add/Deduct adjustment amount for wholesale rough reg_adj_whole_xclean Regional adjustment amount for wholesale extra clean reg_adj_whole_clean Regional adjustment amount for wholesale clean reg_adj_whole_avg Regional adjustment amount for wholesale average reg_adj_whole_rough Regional adjustment amount for wholesale rough base_retail_xclean Retail Extra Clean value before any adjustments base_retail_clean Retail Clean value before any adjustments base_retail_avg Retail Average value before any adjustments base_retail_rough Retail Rough value before any adjustments mileage_adj_retail_xclean Mileage adjustment amount for retail extra clean mileage_adj_retail_clean Mileage adjustment amount for retail clean mileage_adj_retail_avg Mileage adjustment amount for retail average mileage_adj_retail_rough Mileage adjustment amount for retail rough ad_adj_retail_xclean Automatic add/deduct adjustment amount for retail extra clean ad_adj_retail_clean Automatic add/deduct adjustment amount for retail clean ad_adj_retail_avg Automatic add/deduct adjustment amount for retail average ad_adj_retail_rough Automatic add/deduct adjustment amount for retail rough reg_adj_retail_xclean Regional adjustment amount for retail extra clean reg_adj_retail_clean Regional adjustment amount for retail clean reg_adj_retail_avg Regional adjustment amount for retail average reg_adj_retail_rough Regional adjustment amount for retail rough base_tradein_clean Trade-in Clean value before any adjustments base_tradein_avg Trade-in Average value before any adjustments base_tradein_rough Trade-in Rough value before any adjustments mileage_adj_tradein_clean Mileage adjustment amount for trade-in clean mileage_adj_tradein_avg Mileage adjustment amount for trade-in average mileage_adj_tradein_rough Mileage adjustment amount for trade-in rough ad_adj_tradein_clean Automatic add/deduct adjustment amount for trade-in clean ad_adj_tradein_avg Automatic add/deduct adjustment amount for trade-in average ad_adj_tradein_rough Automatic add/deduct adjustment amount for trade-in rough reg_adj_tradein_clean Regional adjustment amount for trade-in clean reg_adj_tradein_avg Regional adjustment amount for trade-in average Return To Table of Contents

Version: 2.0

Data Element Name Element Description reg_adj_tradein_rough Regional adjustment amount for trade-in rough base_finadv Finance Advance amount before any adjustments mileage_adj_finadv Mileage adjustment amount for Finance Advance ad_adj_finadv Automatic add/deduct adjustment amount for Finance Advance reg_adj_finadv Regional adjustment amount for Finance Advance base_resid12 The 12 month residual value before any adjustments base_resid24 The 24 month residual value before any adjustments base_resid30 The 30 month residual value before any adjustments base_resid36 The 36 month residual value before any adjustments base_resid42 The 42 month residual value before any adjustments base_resid48 The 48 month residual value before any adjustments base_resid60 The 60 month residual value before any adjustments base_resid72 The 72 month residual value before any adjustments mileage_adj_resid12 Mileage adjustment amount for the 12 month residual value mileage_adj_resid24 Mileage adjustment amount for the 24 month residual value mileage_adj_resid30 Mileage adjustment amount for the 30 month residual value mileage_adj_resid36 Mileage adjustment amount for the 36 month residual value mileage_adj_resid42 Mileage adjustment amount for the 42 month residual value mileage_adj_resid48 Mileage adjustment amount for the 48 month residual value mileage_adj_resid60 Mileage adjustment amount for the 60 month residual value mileage_adj_resid72 Mileage adjustment amount for the 72 month residual value ad_adj_resid12 Automatic add/deduct adj amount for the 12 month residual value ad_adj_resid24 Automatic add/deduct adj amount for the 24 month residual value ad_adj_resid30 Automatic add/deduct adj amount for the 30 month residual value ad_adj_resid36 Automatic add/deduct adj amount for the 36 month residual value ad_adj_resid42 Automatic add/deduct adj amount for the 42 month residual value ad_adj_resid48 Automatic add/deduct adj amount for the 48 month residual value ad_adj_resid60 Automatic add/deduct adj amount for the 60 month residual value ad_adj_resid72 Automatic add/deduct adj amount for the 72 month residual value end_of_term_value The end of term value based on the user supplied maturity date. This value is adjusted for mileage, automatic add/deducts and market “U” for used cars, “P” for power sports or “T” for trucks. descriptionScore The score assigned to the vehicle description and model number provided by the customer when compared to the Black Book description and model number for this vehicle Return To Table of Contents

Version: 2.0 Appendix ‘B’ – US Valuation Schema (continued) ndix ‘B’ – US Valuation Schema (continued bborgdesc The original Black Book description for this vehicle - before the translation step. bbmoddesc The modified Black Book description for this vehicle – after the translation step. custorgdesc The original customer description – as passed into the getVINValues function in the sVehicleDescription parameter. custmoddesc The modified customer description – after the translation step custmodnumber The customer model number – as passed into the getVINValues function in the sModelNumber parameter. matchingwords The list of words from the customer description and model number that matched words in the Black Book description and model number bbr_score For future use - Black Book Risk Score bbf_rating For future use - Black Book Fraud Rating

Version: 2.0 Appendix ‘C’ – Canadian Valuation Schema

When the country code is set to ‘C’ for Canadian the getVINValues methods will return the XML schema outlined in the table on the next page. The difference lies in how regional adjustments are performed. Each province is represented in the Canadian schema, so theoretically each province could have a different adjustment amount. Whereas, in the U.S. schema the states are grouped by region numbers.

Note: Canadian mileage conversion

When entering iMilesPerYear if the country is set to "A" for all or left blank and the VIN is not found in the US database but is found in the Canadian data base the mileage will be converted to kilometers by multiplying it by 1.609344.

When entering iMileage if the country is set to "A" for all or left blank the following conditions apply.

1. If the entry for sState is a valid US state and the VIN is not found in the US database but is found in the Canadian database the mileage entered is then converted to kilometers.

2. If the sState parameter is left blank and the VIN is not found in the US database but is found in the Canadian database the mileage entered is then converted to kilometers.

Return To Table of Contents

Version: 2.0

Appendix ‘C’ – Canadian Valuation Schema (continued)

Data Element Name Element Description Country ‘C’ = Canadian frequency 'D' = daily, ‘B’ = Bi-weekly Year 4 digit year Make i.e. Ford Model i.e. Expedition Series i.e. XLT Style i.e. 4D Utility VIN_year 10th position of VIN whole_xclean Adjusted Wholesale extra clean value whole_clean Adjusted Wholesale clean value whole_avg Adjusted Wholesale average value whole_rough Adjusted Wholesale rough value retail_xclean Adjusted Retail extra clean value retail_clean Adjusted Retail clean value retail_avg Adjusted Retail average value retail_rough Adjusted Retail rough value tradein_clean Adjusted Trade-in clean value tradein_avg Adjusted Trade-in average value tradein_rough Adjusted Trade-in rough value Finadv Adjusted Finance advance value resid12 Adjusted 12 Month residual value resid24 Adjusted 24 Month residual value resid30 Adjusted 30 Month residual value resid36 Adjusted 36 Month residual value resid42 Adjusted 42 Month residual value resid48 Adjusted 48 Month residual value resid60 Adjusted 60 Month residual value resid72 Adjusted 72 Month residual value AB_Province Alberta Province Adjustment BC_Province British Columbia Prov. Adjustment MB_Province Manitoba Province Adjustment NB_Province New Brunswick Province Adjustment NL_Province Newfoundland Province Adjustment NT_Province Northwest Territories Province Adjustment

Return To Table of Contents

Version: 2.0 Appendix ‘C’ – Canadian Valuation Schema (continued)

Data Element Name Element Description NS_Province Nova Scotia Province Adjustment NU_Province Numavut Territory Province Adj. ON_Province Ontario Province Adjustment PE_Province Prince Edward Isl. Province Adj. QC_Province Quebec Province Adjustment SK_Province Saskatchewan Province Adjustment YT_Province Yukon Territory Province Adjustment group_number MSRP Manufacturer's Suggested Retail Price ERT Equipped retail value Mileage_category actualdate The date the values were published full_VIN Positions 1-8 and 10 of the VIN full_UVC 10 digits = year + make code + UVC model_number Manufacturer model number veh_class Vehicle Class Code wheel_base i.e. 108.5 base_HP i.e. 125 @ 6000 taxable_HP i.e.. 17.1 GVW i.e. 2601 cylinders i.e. 8 fuel_type i.e. Gas tire_size i.e. 185/65R14 Engine i.e. 3.8L V6 EFI transmission i.e. A = automatic drivetrain i.e. FWD base_whole_xclean Wholesale Extra Clean value before any adjustments base_whole_clean Wholesale Clean value before any adjustments base_whole_avg Wholesale Average value before any adjustments base_whole_rough Wholesale Rough value before any adjustments mileage_adj_whole_xclean Mileage adjustment amount for wholesale extra clean mileage_adj_whole_clean Mileage adjustment amount for wholesale clean mileage_adj_whole_avg Mileage adjustment amount for wholesale average Mileage_adj_whole_rough Mileage adjustment amount for wholesale rough ad_adj_whole_xclean Automatic add/Deduct adjustment amount for wholesale extra clean Return To Table of Contents

Version: 2.0 Appendix ‘C’ – Canadian Valuation Schema (continued)

Data Element Name Element Description ad_adj_whole_clean Automatic add/Deduct adjustment amount for wholesale clean ad_adj_whole_avg Automatic add/Deduct adjustment amount for wholesale average ad_adj_whole_rough Automatic add/Deduct adjustment amount for wholesale rough reg_adj_whole_xclean Regional adjustment amount for wholesale extra clean reg_adj_whole_clean Regional adjustment amount for wholesale clean reg_adj_whole_avg Regional adjustment amount for wholesale average reg_adj_whole_rough Regional adjustment amount for wholesale rough base_retail_xclean Retail Extra Clean value before any adjustments base_retail_clean Retail Clean value before any adjustments base_retail_avg Retail Average value before any adjustments base_retail_rough Retail Rough value before any adjustments mileage_adj_retail_xclean Mileage adjustment amount for retail extra clean mileage_adj_retail_clean Mileage adjustment amount for retail clean mileage_adj_retail_avg Mileage adjustment amount for retail average mileage_adj_retail_rough Mileage adjustment amount for retail rough ad_adj_retail_xclean Automatic add/deduct adjustment amount for retail extra clean ad_adj_retail_clean Automatic add/deduct adjustment amount for retail clean ad_adj_retail_avg Automatic add/deduct adjustment amount for retail average ad_adj_retail_rough Automatic add/deduct adjustment amount for retail rough reg_adj_retail_xclean Regional adjustment amount for retail extra clean reg_adj_retail_clean Regional adjustment amount for retail clean reg_adj_retail_avg Regional adjustment amount for retail average reg_adj_retail_rough Regional adjustment amount for retail rough base_tradein_clean Trade-in Clean value before any adjustments base_tradein_avg Trade-in Average value before any adjustments base_tradein_rough Trade-in Rough value before any adjustments mileage_adj_tradein_clean Mileage adjustment amount for trade-in clean mileage_adj_tradein_avg Mileage adjustment amount for trade-in average mileage_adj_tradein_rough Mileage adjustment amount for trade-in rough ad_adj_tradein_clean Automatic add/deduct adjustment amount for trade-in clean ad_adj_tradein_avg Automatic add/deduct adjustment amount for trade-in average ad_adj_tradein_rough Automatic add/deduct adjustment amount for trade-in rough reg_adj_tradein_clean Regional adjustment amount for trade-in clean reg_adj_tradein_avg Regional adjustment amount for trade-in average Return To Table of Contents

Version: 2.0

Appendix ‘C’ – Canadian Valuation Schema (continued)

Data Element Name Element Description reg_adj_tradein_rough Regional adjustment amount for trade-in rough base_finadv Finance Advance amount before any adjustments mileage_adj_finadv Mileage adjustment amount for Finance Advance ad_adj_finadv Automatic add/deduct adjustment amount for Finance Advance reg_adj_finadv Regional adjustment amount for Finance Advance base_resid12 The 12 month residual value before any adjustments base_resid24 The 24 month residual value before any adjustments base_resid30 The 30 month residual value before any adjustments base_resid36 The 36 month residual value before any adjustments base_resid42 The 42 month residual value before any adjustments base_resid48 The 48 month residual value before any adjustments base_resid60 The 60 month residual value before any adjustments base_resid72 The 72 month residual value before any adjustments mileage_adj_resid12 Mileage adjustment amount for the 12 month residual value mileage_adj_resid24 Mileage adjustment amount for the 24 month residual value mileage_adj_resid30 Mileage adjustment amount for the 30 month residual value mileage_adj_resid36 Mileage adjustment amount for the 36 month residual value mileage_adj_resid42 Mileage adjustment amount for the 42 month residual value mileage_adj_resid48 Mileage adjustment amount for the 48 month residual value mileage_adj_resid60 Mileage adjustment amount for the 60 month residual value mileage_adj_resid72 Mileage adjustment amount for the 72 month residual value ad_adj_resid12 Automatic add/deduct adj amount for the 12 month residual value ad_adj_resid24 Automatic add/deduct adj amount for the 24 month residual value ad_adj_resid30 Automatic add/deduct adj amount for the 30 month residual value ad_adj_resid36 Automatic add/deduct adj amount for the 36 month residual value ad_adj_resid42 Automatic add/deduct adj amount for the 42 month residual value ad_adj_resid48 Automatic add/deduct adj amount for the 48 month residual value ad_adj_resid60 Automatic add/deduct adj amount for the 60 month residual value ad_adj_resid72 Automatic add/deduct adj amount for the 72 month residual value end_of_term_value The end of term value based on the user supplied maturity date. This value is adjusted for mileage and automatic add/deducts market “U” for used cars, “P” for power sports or “T” for trucks. descriptionScore The score assigned to the vehicle description and model number provided by the customer when compared to the Black Book description and model number for this vehicle

Version: 2.0 Appendix ‘C’ – Canadian Valuation Schema (continued) bborgdesc The original Black Book description for this vehicle - before the translation step. bbmoddesc The modified Black Book description for this vehicle – after the translation step. custorgdesc The original customer description – as passed into the getVINValues function in the sVehicleDescription parameter. custmoddesc The modified customer description – after the translation step custmodnumber The customer model number – as passed into the getVINValues function in the sModelNumber parameter. matchingwords The list of words from the customer description and model number that matched words in the Black Book description and model number bbr_score For future use - Black Book Risk Score bbf_rating For future use - Black Book Fraud Rating

Appendix ‘D’ – Power Sports Valuation Schema

The table below lists all the data elements for valuation of power sports vehicles. The same schema is used for U.S. and Canadian power sports vehicles. Note that all data elements will be returned regardless of whether your account allows access. For those elements where access is denied the element will be empty or zero filled.

Data Element Name Element Description Country “U” for United States, “C” for Canada Frequency “M” for Monthly, other values possible in the future Vehicle_id Unique vehicle identifier (could change) Full_vin Positions 1-8 and 10 of the VIN Year 4 digit year Make i.e. Honda Model i.e. CR125R Full_uvc 10 digit id that never changes Veh_class i.e. Off Road MSRP Manufacturer Suggested Retail Price Cylinders i.e. 1 Displacement i.e. 125 Actualdate Valuation publish date Whole_avg Wholesale average Retail_avg Retail average

Version: 2.0 Tradein_clean Trade-in clean value Tradein_fair Trade-in fair value Finadv Finance advance

Appendix ‘E’ – Truck Valuation Schema

The table below lists all the data elements for the truck vehicle valuation dataset. Note that all data elements will be returned regardless of whether your account allows access. For those elements where access is denied the element will be empty or zero filled.

Data Element Name Element Description Country “U” for United States, other values possible in the future Frequency “M” for Monthly, other values possible in the future Vehicle_id Unique vehicle identifier (could change) Year i.e. 2004 Make i.e. Autocar Model i.e. WX-Series Style i.e. WX42 81"BBC Low COE Truck 4X2 Full_vin Positions 1-8 and 10 of the VIN i.e. 5VCD16CD4 Full_uvc 10 digit id that never changes i.e. 2004987001 Model_number i.e. D*6** Manufacturer i.e. Autocar Veh_class i.e. Heavy Duty Truck Mileage_category i.e. HC Mileage_category_desc i.e. Heavy Duty Construction/Vocational Trucks & Tractors Price_includes i.e. AC, PS Actualdate Valuation publish date MSRP Manufacturer Suggested Retail Price Whole_avg Wholesale average Whole_rough Wholesale rough Retail_avg Retail average Finadv Finance advance GVW i.e. 37000-50000 GCW Cylinders i.e. 6 Cyl Diesel base_hp i.e. 280-330HP Engine_liters i.e. 10.3L-10.8L transmission i.e. 6 Spd Automatic

Version: 2.0

Appendix ‘E’ – Truck Valuation Schema (continued)

Data Element Name Element Description Base_whole_avg Wholesale Average before any adjustments base_whole_rough Wholesale rough before any adjustments base_retail_avg Retail average before any adjustments base_finadv Finance advance before any adjustments mileage_adj_whole_avg Mileage adjustment amount for wholesale average mileage_adj_whole_rough Mileage adjustment amount for wholesale rough mileage_adj_retail_avg Mileage adjustment amount for retail average mileage_adj_finadv Mileage adjustment amount for finance advance

Confidential Page 35 1/9/2018