# validation.uk-utr

Checks the check digit of an HMRC Unique Taxpayer Reference (UTR), the ten
digit reference for Self Assessment, partnerships and Corporation Tax, and
returns it as ten plain digits.

A PASS IS NOT A TAXPAYER. The check digit catches most typing mistakes; it
does not say HMRC issued the reference, or issued it to this person or company.

## The check

The first digit is the check digit. Multiply the second to tenth digits by 6,
7, 8, 9, 10, 5, 4, 3 and 2, add them up and take the remainder on dividing by
11. The check digit for remainders 0 to 10 is 2, 1, 9, 8, 7, 6, 5, 4, 3, 2, 1:
that is 11 minus the remainder, except that remainders 0 and 1 give 2 and 1.
The often-quoted shortcut "(11 - remainder) mod 11" gets those two remainders
wrong and rejects real references such as HMRC's own test reference
2234567890.

HMRC has not published the algorithm as a specification. The weights and the
remainder table here are taken from HMRC's own open-source reference checker,
and its valid and invalid test references are vectors here.

## Input

HMRC's design pattern for asking for a UTR allows spaces and a K at the start
or end ("1234567890K" is how Self Assessment online shows it). ASCII spaces are
ignored anywhere, and one K (either case) is removed from the start or,
failing that, the end. Anything else is `bad-character`.

The same pattern allows 13-digit forms and says to remove "extra digits", but
does not say which three digits are extra. Rather than guess, a 13-digit value
is refused with its own reason, `thirteen-digits`, so a form can ask for the
ten-digit reference.

| reason | meaning (checked in this order) |
|---|---|
| `empty` | nothing but spaces, or not a string |
| `bad-character` | a character other than a digit or space, after one K is removed |
| `thirteen-digits` | a 13-digit form (see above) |
| `bad-length` | any other length than ten digits |
| `bad-check-digit` | the first digit does not match |

## Sources

- HMRC, hmrc/domain on GitHub, `referencechecker/ReferenceChecker.scala`
  (`UtrReferenceChecker`, `SelfAssessmentReferenceChecker`) and
  `ModulusCheckerSpec.scala`, read 23 September 2026:
  https://github.com/hmrc/domain
- HMRC design patterns, "Unique Taxpayer Reference":
  https://design.tax.service.gov.uk/hmrc-design-patterns/unique-taxpayer-reference/

2.0.0 renames the function from `ukUtr` to `validateUkUtr` (`validate_uk_utr` in Python and
Rust), so every validator that returns a result record is `validateX` and
every one that returns a bool is `isX`. Nothing else changed; 1.0.0 stays
published under the old name.