About Our Finance Term, Plan & Mileage Boxes APIs
Our Finance Term, Plan & Mileage Box APIs generate selection boxes for users to choose their:
- finance term (the number of months for a finance agreement);
- finance plan (the number of advance and remaining payments for the finance agreement; and
- annual vehicle mileage.
The finance term and plan boxes are normally linked so that a change in the finance term generates a recalibration of the finance payment plans available.
Dataset: Term
The dataset provides term options for a finance agreement denominated in months, ranging from 12 to 60 months.
The term increments can be 1 or 12 months. A 1 month increment will produce 12, 13, 14, etc months in the dataset. A 12 month increment will produce 12, 24, 36, etc months.
The 't_inc' setting determines the increment and can be 'm' for months (12, 13, 14 etc) or 'a' for annual (12, 24, 36 etc).
If the 't_inc' setting is omitted the default dataset is returned as annual (12, 24, 36 etc).
The starting and ending number of months can be set using the 't_min' and 't_max' requests.
A 't_min' setting denotes the minimum number of months (e.g. 12) and 't_max' denotes the maximum number (e.g. 60).
't_min' and 't_max' must be a multiple of 12.
If 't_min' or t_max' are omitted or are not a multiple of 12 the default values are 12 and 60 respectively.
12 and 60 are, respectively, also the minimim and maximum values (months) permitted.
The content of the dataset is an 'integer' type value.
Dataset: Plan
The plan dataset provides the finance plan payment options related to the selected finance term, i.e. the number of advance monthly payments at the beginning of the agreement and the remaining number of payments during the term.
The payment plan is usually expressed as a combination of the number of advance payments required and the term (in months) minus 1 and this protocol is used in the dataset.
For example, the payment plan options for a 36 month term agreement may be expressed as 1+35, 2+35, 3+35 etc.
The content of the dataset is an integer for the number of advance payments (e.g. 3) and 'string' type value for the plan expression (e.g. '3+35').
Dataset: Miles
The miles dataset provides the annual mileage options related for the finance term, i.e. the number of annual miles allowed in the finance contract.
The miles are expressed as an unformatted number of '000s of miles per annum.
For example, 10000 miles per annum is expressed without commas.
The content of the dataset is an 'integer' type value.
Dataset: General Information
The dataset can be provided in 'JSON' or 'XML' format.
You can choose the type of data returned in your HTTPS request by declaring 'json' or 'xml' in the 'd_Type' element of the request string.
JSON is the default type for the dataset if no 'd_Type' is set.
Our Demo
Our demonstrator provides an illustration of how the API delivers a term, plan and mileage selection boxes for finance using XML.
We will display the relative HTTPS {GET} requests for each stage of car selection; you can copy and paste the sample request strings into a browser address bar to see the raw XML data returned for the request (right click on the browser page displayed and you will see the XML dataset).
You can also substitute XML for JSON when you perform the 'copy|paste' exercise.
The finance term box is then linked to a call for a finance plan selection box allowing the user to choose the number of advance payments for a finance agreement relative to the number of months in the finance term.
For example, the user selects a 36 month term and can then choose a finance plan.
The plan displayed will comprise the number of months for the deposit and the term period -1, e.g. 1+35, 2+35, 3+35 etc up to 11 + (term -1).
{GET} Requirements
The {GET} request follows standard HTTPS key:value pair protocols. No response will be given for an HTTP request.
The {GET} request for a car's price only requires our standard security login/session token and the car's CAPID.
The manufacturer, range and model name are not required for the calculation, but these items will be returned as part of the dataset for verification purposes.
The CAPID must be for a vehicle currently for sale new in the UK - a CAPID for a discontinued model or retired derivative will not return a dataset.
A dataset will only be provided where CAP-HPI has a published manufacturer's list price for a vehicle - new vehicle model ranges/derivatives may not return a dataset.
Data Retrieval
Once you have selected a vehicle below click on the 'Price' button to see a returned dataset.
You will also see the entire {GET} request string as an example and the returned dataset structured as a typical online representation of XML for the car.
This will include the dataset XML node descriptions so that you can see the schema.
The returned dataset for price provides the individual price components as published by CAP-HPI.
Once you've gone through the selection process you can also see a sample implementation of the price list.
Click on the 'View Sample Implementation' button to open a new browser window with a sample web display page.
VAT
The values provided in the dataset are VAT inclusive.
To calculate the VAT exclusive equivalent values for the list price and delivery charges divide the relevant dataset values by 1.2 (exclude the registration fee and VED as these items do not attract VAT).
Security
A session token is created on initial login and must be included as a cookie with all HTTPS requests or the request will fail.
If the user's browser does not allow functional cookies then the {GET} request will become orphaned and the request cannot be linked to any other requests in the same session.
If the session token is not included then the session will be terminated, any data created in the session may be erased at the server and the user may need to re-authenticate with a new session.
For security reasons the HTTPS protocol must be used for all {GET} requests so that all data passed between the browser and the server is encrypted, including the session token.
Pair:Value Summary
All
d_type: xml or json for the required return data type (json if not specified)
Term
t_min: an integer divisible by 12 (12, 24, 36, etc)
t_max: an integer divisible by 12 (36, 48, 60, etc)
t_inc: 'a' for annual term increments (12, 24, 36, etc) or 'm' for months (12, 13, 14, etc)
Plan
p_sel: an integer for the total numbr of months for the finance term (e.g. 12, 24, 36, etc)
p_min: an integer for the start value for the plan advance payments (e.g. 1)
p_max: an integer for the end value for the plan advance payments (e.g. 11)
p_inc: an integer for the increments for the payment plan options - must be 1 or 3
Miles
m_min: an integer for the start value for the annual miles allowed during the finance term (e.g. 10000)
m_max: an integer for the end value for the plan advance payments (e.g. 30000)
m_inc: an integer for the increments for the payment plan options (e.g. 5000)