Using the Correct NI Letter

When calculating National Insurance Contributions, it is important to select the correct NI Category Letter.

The API includes a special pre-calculation rule to ensure the correct letter is selected.

By default, the pre-calculation rule ("NiSetExpectedLetterRule") will automatically override any NI Category Letter that does not match the expected letter.

This rule behaviour can be disabled, using the techniques described in the pre-calculation rule page.

Manually selecting the correct NI Category Letter

The following process flow chart can be used to identify the correct NI Category Letter for a given employee. Using the employee age and flag options, it is possible to determine the category letter to be used.

NI Liability Flags

The API includes some special flag options that can be used to control the NI Category Letter. The flag values are set against the employee prior to the pay run calculation process.

Flag Options

  • Is Fully Liable
    The employee is fully liable for National Insurance contributions.
  • Has Other Job
    Employee can defer National Insurance because they’re already paying it in another job.
  • Is Female Entitled To Reduced Rate
    For married women and widows entitled to pay reduced National Insurance.
  • Is Not Liable
    The employee is exempt from paying National Insurance contributions.
  • Is Apprentice
    The employee is working via an apprenticeship scheme
  • Is Free Port Worker
    The employee is working in a free port area

Setting NI Liability Flags on the Employee

You can set liability flags on the Employee using a PATCH request.

curl -X PATCH \
  '' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml' \
  -d '<?xml version="1.0"?>
<Employee xmlns:xsd="" xmlns:xsi="">
    <NicLiability>HasOtherJob IsFemaleEntitledToReducedRate</NicLiability>
curl -X PATCH \
  '' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "Employee": {
    "EffectiveDate": "2017-04-30",
	"NicLiability": "HasOtherJob IsFemaleEntitledToReducedRate"