niho / personal-number / PersonalNumber.UK

Parse UK National Insurance Numbers.

See https://www.gov.uk/hmrc-internal-manuals/national-insurance-manual/nim39110 for specification, and see https://design-system.service.gov.uk/patterns/national-insurance-numbers/ for designing your UI.

In particular:

Definition


type NationalInsuranceNumber

An opaque type representing a valid national insurance number.

Errors


type ValidationError
    = InvalidLength
    | InvalidFormat FormatError
    | InvalidPrefix PrefixError
    | InvalidSuffix

If the parsing fails an error of this type is returned.

A National Insurance Number is made up of a 2 letter prefix, 6 numbers and a final letter, which is always A, B, C, or D.

It looks something like this:

QQ 12 34 56 A

All prefixes are valid except:

You could turn these errors into strings something like this:

errorToString : ValidationError -> String
errorToString e =
    case e of
        InvalidLength ->
            "National Insurance Numbers should have 9 characters, like  QQ 12 34 56 C  or  QQ123456C."

        InvalidFormat DoesNotStartWithTwoLetters ->
            "National Insurance Numbers should start with two letters, like  QQ 12 34 56 C  or  QQ123456C."

        InvalidFormat DoesNotEndWithALetter ->
            "National Insurance Numbers should end with a single letter A, B, C or D, like  QQ 12 34 56 C  or  QQ123456C."

        InvalidFormat DoesNotHaveSixNumbersInTheMiddle ->
            "National Insurance Numbers should have six digits in the middle, like  QQ 12 34 56 C  or  QQ123456C."

        InvalidPrefix DisallowedPrefixLetter ->
            "D, F, I, Q, U, and V are not allowed in the first two letters of National Insurance Numbers."

        InvalidPrefix DisallowedSecondLetterO ->
            "O is not allowed in the second letter of National Insurance Numbers."

        InvalidPrefix DisallowedPrefix ->
            "BG, GB, KN, NK, NT, TN and ZZ are not allowed at the start of National Insurance Numbers."

        InvalidSuffix ->
            "The last letter of National Insurance Numbers can only be A, B, C or D."

Strings

fromString : String -> Result ValidationError NationalInsuranceNumber

Parse a string into a National Insurance Number.

toString : NationalInsuranceNumber -> String

Converts a national insurance number to string representation in the short format that is commonly used for database storage (AB123456C).

display : NationalInsuranceNumber -> String

Format a national insurance number in the long format that is commonly used for human communication (AB 12 34 56 C).

JSON

decoder : Json.Decode.Decoder NationalInsuranceNumber

Decode a National Insurance Number.

encode : NationalInsuranceNumber -> Json.Encode.Value

Encode a national insurance number into a JSON value.