About Our Salary Sacrifice Employee Profile API
Our Salary Sacrifice Employee Profile API posts a profile of an employee's salary, pension and tax position for a Salary Sacrifice analysis.
If you wish to include the costs for the employer you will also need a completed business profile; click on this link to do that.
Using {POST} the personal profile passes a dataset to our server to prepare for a analysis of the cost and tax implications of a Salary Sacrifice to obtain a company car.
The employee profile is conditional and the data submitted depends on whether the customer is a member of a company pension plan. The profile therefore covers:
- The employee's salary or wages
- The employee's tax code and tax/NIC liabilities from employment income
- Dependent: Company pension scheme contributions rate
Dataset
When a completed profile is submitted a return dataset is provided to verify the submission.
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 Employee Profile API delivers a summary of the driver's employment income using XML.
To obtain an analysis:
- create a profile for the customer by selecting the appropriate responses to prompts;
- click on the 'POST' button.
We will display the relative HTTPS {POST} requests for relevant stages of creating the profile; 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).
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)
Tax Status Dependent
p_p_int: the employee's normal pay interval as a string variable, 'W' for weekly and 'M' for monthly
p_t_res: the employee's place of tax residence as a string (different regions within the UK may have variations in tax rates and rate bands etc)
- "E"; England or N. Ireland
- "S"; Scotland
- "W"; Wales
- "X"; Elsewhere
The employee's choice will impact on the PAYE tax codes displayed as explained below.
(
Our API does not currently apply to residents of regions not listed above. If 'Elsewhere' is selected you should generate a warning and terminate the session.)
p_t_code: the type of PAYE tax code applicable to the employee based on the typical UK tax codes (including regional variatons); a string variable is used as follows:
- "L"; Numbers first, then a letter (e.g. 1250L)
- "B"; BR
- "N"; NT
- "O"; 0T
- "H"; D0
- "A"; D1
- "S"; Something else
For regional variations in PAYE codes an appropriate prefix ("S" for Scotland, "C" for Wales") should be displayed to the user.
For Wales the selectable items and explanations should be:
- "L"; 'C', then numbers, then a letter (e.g. C1250L)
- "B"; CBR
- "N"; CNT
- "O"; C0T
- "H"; CD0
- "A"; CD1
- "S"; Something else
In the case of Scotland the selectable items and explanations should be:
- "L"; 'S', then numbers, then a letter (e.g. S1250L)
- "B"; SBR
- "N"; SNT
- "O"; S0T
- "I"; SD0
- "H"; SD1
- "A"; SD2
- "S"; Something else
This is to accommodate differences in tax rate bands etc in the UK.
Please note that 'K" type codes (which are, effectively, negative personal tax allowances) are not currently supported in the API.
p_t_c_all: an integer comprising of the employee's tax code numerals where this has an 'L' or 'T' suffix (e.g. 1250 for 1250L
Pay Components
p_pgp: a double type variable for the employee's monthly or weekly pay
p_pot: a double type variable for the employee's monthly or weekly overtime
p_pbo: a double type variable for the employee's monthly or weekly bonuses
p_pbe: a double type variable for the employee's monthly or weekly taxable benefits
p_pto: a double type variable for the employee's monthly or weekly total pay (we recommend that this is a calculated field based on responses to the other pay inputs
Pension Scheme Membership Dependent
The employee should be offered the opportunity to indicate membership of an employer provided pension scheme (such as a radiobutton option).
Where the employee indicates pension scheme membership then checkboxes or similar devices should indicate which aspects of pay are eleigible for pension scheme contributions and the following pair:values should be used in the {POST} request:
p_pen_m: a string variable for indicating of the employee is ("Y") or is not ("N") a pension scheme member
p_pen_inc: a string type variable for each element of pay eligible for the pension scheme as follows:
- "P"; Pay
- "O"; Overtime
- "B"; Bonus
- "X"; Other pay
- "Y"; Benefits
The string can be a concatenation of any/all of the above in any order, e.g. 'POBXY' is acceptable.
p_pen_r: a double type variable for the employee's pensions contribution rate (e.g. 7.5 for a 7.5% employee pension contributions rate)
p_pen_con: a double type variable for the amount of the employee's monthly or weekly pensions contributions