About Our Business Car 'Lease Or Buy' API
Our Business Car 'Lease Or Buy' API provides an analysis of the cost and cash-flow impact on a fleet operator of leasing vs buying a new car over a specified term and mileage.
We also have 'Lease or Buy' analysers for:
The API can also analyse vans, though the vehicle selection process is slightly different due to variations in vehicle excise duty, business tax relief and VAT recovery between cars and vans.
A separate selection module is therefore used for vans and you can switch to it here.
Using {GET} and {POST} the 'Lease or Buy' API passes a series of datasets to our server to build up an analysis of the costs and cash-flows of leasing a vehicle vs buying on finance, with a base-line analysis of the cost of outright purchase.
Using the returned datasets of vehicle finance costs and discounted cash-flows you can built a comprehensive comparison of the costs of leasing vs buying including side-by-side analysis and summaries of the results.
The requests for a 'Lease Or Buy' (LOB) analysis are a composite of the specific LOB API and APIs responding to other {GET} and {POST} requests; you can find details of the ancillary requests here:
Dataset
A series of datasets is returned according to the type of vehicle and finance selected by the user.
Once the type of vehicle is selected, listboxes are populated with manufacturers, vehicle ranges and models.
For each type of finance selected two datasets are returned, one on selection of a finance method and one on calculation of the LOB analysis:
- Selection: verification of the vehicle (CAPID, manufacturer, range and model) and finance selection (term, plan and annual miles);
- Calculation: the costs for the selected finance method (purchase price, finance rentals, residual value, other costs (VED etc).
The dataset can be provided in 'JSON' or 'XML' format and 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 LOB API delivers an analysis for cars using XML.
To obtain an analysis:
- create a profile for the business;
- choose a vehicle
- select the finance term, payment plan and annual or total mileage;
- choose the finance to be included in the analysis; and
- click on the 'Calculate' button.
We will display the relative HTTPS {GET} requests for each stage of 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.
{GET} and {POST} Requirements
The {GET} and {POST} requests follow standard HTTPS key:value pair protocols. No response will be given for an HTTP request.
All requests must have a valid session token attached as a cookie otherwise the request will become orphaned (see below).
An analysis will only be provided where CAP-HPI has a published ID for the selected vehicle - new vehicle model ranges/derivatives will not return a dataset until CAP-HPI publishes an ID.
Data Retrieval
Once you have selected a vehicle, term and mileage below click on the 'Calculate' 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 the residual value also provides manufacturer/model/derivative verification and the chosen term and mileage.
VAT
The values provided in the dataset are VAT inclusive.
To calculate the VAT exclusive equivalent residual value divide the relevant dataset value by 1.2.
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)
CAPID: the vehicle's CAP ID code (an integer only)
Finance
f_type: a two or three letter code for the type of finance from the following:
- CH - Business Contract Hire
- CP - Business Contract Purchase
- HP - Business Hire Purchase
- FL - Business Finance Lease
- BL - Business Balloon Leasse
- PCH - Personal Contract Hire
- PCH - Personal Contract Purchase
- PHP - Personal Hire Purchase
Finance Rate and Plan
f_rate: a 'double' type variable for the interest rate (e.g. 5.55 - this will be returned as a decimal in the verification dataset)
f_term: an integer type variable for the finance term in months (e.g. 12, 24, 36, 48, 60)
f_plan: an integer type variable for the number of advance payments from 1 to 12 (e.g. 3 for '3+35' or 9 for '9+23')
Optional - finance dependent
f_oh: a 'double' type variable for a monthly finance overhead either instead of, or in addition to, the interest rate (e.g. 10.50)
f_a_miles: an integer type value for the number of annual contract miles for business or personal contract hire, contract hire or balloon lease(e.g. 10000)
f_fee: a 'double' type variable for a VAT exclusive administration or document fee (e.g. 199.99)
Vehicle
The following values can be set to '0' but should be present in all {GET} requests:
v_l_price: a double type variable for the VAT inclusive sale price of the vehicle excluding options, delivery charges, registration fee or vehicle excise duty (e.g. 20000.00)
v_o_price: a double type variable for the VAT inclusive price of factory fitted options (e.g. 2000.00)
v_d_price: a double type variable for the VAT inclusive price of local dealer fitted options (e.g. 500.00)
v_dc_price: a double type variable for the VAT inclusive cost of delivery charges, number plates, etc (e.g. 750.00)
v_r_fee: a double type variable for the initial registration fee for new cars (e.g. 55.00)
v_ved1: a double type variable for the first year vehicle excise duty (e.g. 450.00)
v_otr: a double type variable for the total on-the-road price of the car (e.g. 20000.00)
Optional - finance dependent
v_mfv: an intger type variable for the minimum guaranteed future value of the vehicle at the specified finance term and contract miles (e.g. 10000) - applies to all finance with a deferral of the residual value, e.g. contract hire, contract purchase, etc
v_rv: an integer type variable for the VAT inclusive forecast residual value of the vehicle at the specified finance term and contract miles (e.g. 10000) - applies to all finance with a deferral of the residual value, e.g. contract hire, contract purchase, etc
v_ved2: a double type variable for the 2nd and subsequent year vehicle excise duty (e.g. 450.00) - applies where the 2nd and subsequent year VED is included in the monthly payments
Other
v_t_co2: an integer for the total CO2 output of the vehicle (including the CO2 outpt from options) in Grammes Per Kilometre (e.g. 110) where this affects the interest rate, VED or overhead (e.g. to compensate for capital allowance restrictions on cars with a higher CO2 output)
v_fuel: a string type variable for the CAP-HPI fuel type code for the vehicle (e.g. 'P', 'D', 'E', etc)
v_rde2: a string type variable for whether or not the diesel vehicles comply with the
RDE2 emissions requirements (e.g. 'Yes' or 'No')
v_type: a string type variable for the vehicle type - 'Car'