Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reference numbers #85

govuk-design-system opened this issue Jan 15, 2018 · 5 comments

Reference numbers #85

govuk-design-system opened this issue Jan 15, 2018 · 5 comments


Copy link

@govuk-design-system govuk-design-system commented Jan 15, 2018


When to use reference numbers, how to generate them and how to display them.


Services that use this pattern:

Anything else

@govuk-design-system govuk-design-system created this issue from a note in GOV.UK Design System Community Backlog (Agreed) Jan 15, 2018
@alphagov alphagov deleted a comment from ignaciaorellana Feb 22, 2018
Copy link

@joelanman joelanman commented Apr 5, 2018

Copy link

@ignaciaorellana ignaciaorellana commented Jul 10, 2018

After a meeting with @owenm6 and the GOV.UK Design System team to talk about authenticating user patterns, we've agreed that what's needed to do is ask the community in government about ‘reference numbers’ (as one example to start) to understand:

  • What are the user needs?
  • How did they decide to go with that approach?
  • Who made the decision? Who was involved?
  • In which stage does it appear in a service?
  • Collect examples
Copy link

@edwardhorsford edwardhorsford commented May 19, 2020

I still refer teams to the Dropbox Paper guidance on reference numbers when they come to designing / implementing reference numbers.

Copied over below, so it doesn't get lost. It would be great to include some of this in the design system - possibly in the patterns section?

Transaction reference numbers

Guidance on transaction reference numbers, tracking numbers, invite codes.

Note: this guidance applies to system generated reference numbers, not user-generated references. For example: whilst systems should be forgiving of users entering in reference numbers, they should be very strict when accepting users' passwords.

The problem

Some services have found that users expect to get a reference number as part of the process, and don't feel they are 'done' until they receive one.

Do you really need a reference number?

Before you decide to design a reference number, ask if users really need one.
Could the same be achieved with the user's name or email address?
If the user has a login, can they see their transaction status and history online?

The solution

If a reference number is necessary, provide a reference that is easy for users to identify, record and quote when needed.

Most users will never need the reference number. But when they do, make sure you've given them a reference that is easy to use.

Make it clear what the reference is for

  • Make it clear what the reference is for and what the user might do with it.
  • If the user should write it down, tell them. But don't rely on them doing this. Make sure the user receives the reference in any case (for example: in an email, text message, or accessible .pdf download).
  • Only give the user one reference for a transaction. Users get confused sorting through different references.

Don't rely on reference numbers

  • Don't force users to remember reference numbers to use your service.
  • Reference numbers may be useful to quickly identify transactions, but have fallbacks in place (e.g. user's name, email address, date of transaction, other transaction content).

Referring to reference numbers

  • Give the reference number a simple, plain English name: e.g. application number, reference number.
  • Don't use internal system names or acronyms (for example: SIK number for System Identification Key number.)

Design principles for good reference numbers

Choice of reference numbers

  • Keep them short (but long enough that you have enough for all future uses)
  • Keep them fixed length.
  • Use just letters and digits.
  • Avoid easily confused characters - commonly I, L, O, Q, S and Z (eg 1 is too visually similar to I and L). The DEC alphabet is an example of where these letters are excluded.
  • If you use a transaction count, it will make it easy for a person to guess or to predict the next person's number. For many services that will be unacceptable, so use reference numbers that are non-sequential / random.
  • Consider starting the reference number with an identifier for the service- eg P-XXX-XXX. This makes communicating to the user how to find the number easier. eg "Your passport reference number starts with 'P' and has 6 more digits".

Showing the reference number to the user

  • Show the number to the user in uppercase (but be case-insensitive for input)
  • Break it into chunks to make it easier to remember and input (e.g. xxx-xxx or xxxx-xxxx).
    • It also "...allows the reader to use prosody (intonation to communicate that they’ve reached the end of the group/code), and It allows for a pause between each to allow the listener to repeat back or interrupt." from Harry Brignull in an IXDA forum.

Collecting the reference number from the user

  • Use good validation to support easy entry - eg convert I and L to 1, let users use spaces, accept lowercase (or uppercase the input).
  • Be forgiving of the commonly confused characters. For example, convert I and L to 1, and o to 0.
  • Accept any punctuation including spaces.
  • If you choose to start the reference number with an identifier, accept the reference with or without the identifier.
  • As with any input, make sure the entry box is big enough to to accommodate the longest possible number plus an allowance for punctuation

Other useful principles

  • Adding a checksum can help to validate reference numbers.
  • Adding contextual information can help call centre and admin staff (e.g. xxxx xx14 for transactions in 2014, and Axxx-xxxx for transactions relating to one service and Mxxxx-xxx for transactions for another service).
  • If a user makes a typo, they shouldn't see someone else's information (in the jargon, 'avoid collisions') - using a good checksum helps avoid this.

IXDA have a good discussion of reference numbers in the commercial sector.

Examples from GOV.UK

Register to vote

The early prototypes of Register to vote did not provide a reference number at completion. And the majority of test participants asked for a number. Once we added a reference number, test participants specifically mentioned the number as a signal that they had finished, and as something they would want to keep (by copying the page to a document, sending the page to email, or taking a snapshot of the page on their phone, etc.).

Our completion page currently looks like this:


The reference number is the first six characters of a SHA-256 hash encoded to hexadecimal. By taking the first six characters we get about 16 million values (we need about 700,000). Using part of a hash makes it unlikely that an error in one character will produce another valid reference number.

A six character reference number is easy to copy and quote. References will contain only the digits 1 through 9 and the letters A through F, avoiding tricky letters like I, O and L.

Example: the Post Code

Copy link

@hannalaakso hannalaakso commented Jun 1, 2020

Thanks @edwardhorsford. Our team would be interested in having this pattern contributed if anyone in the community would like to pick it up.

Copy link

@edwardhorsford edwardhorsford commented Jun 1, 2020

@hannalaakso I'd be up for that, seeing as I contributed to much of the above stuff anyway. Any tips for getting started?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants