Skip to content

Usage

IMPORTANT: You should never need to generate an NHS Number for a live system

Live NHS, CHI, H&C and IHI numbers are always generated by some kind of central authority or registry, such as the NHS Spine in England, and they are assigned to patients, often at or near birth or at the point of becoming a user of that health system.

Unless you represent a central health authority, you should not need to generate an NHS Number for a live system. If you are a patient, you should never need to generate an NHS Number for yourself.

This package is intended for use in testing and development environments where you need to generate NHS Numbers for testing, research purposes, or synthetic data generation.

is_valid()

Returns True if the NHS Number is valid. Returns False if the NHS Number is not valid.

Arguments:

  • nhs_number (required, str): The NHS Number to validate. Valid formats are:
    • 123 456 7890
    • 123-456-7890
    • 1234567890
  • for_region (optional, default=None, Region): If provided, additionally validates number is included within the given Region range.
import nhs_number

nhs_number.is_valid('4698194180')
# True

nhs_number.is_valid('1234567890')
# False

The for_region parameter takes any of the nhs_number.REGION_* constants:

nhs_number.is_valid('7709030025', for_region=nhs_number.REGION_ENGLAND)
# True

Scottish CHI Number validation

At present, this library does not reliably validate Scottish CHI Numbers. This is because the first 6 digits of a Scottish CHI Number must be a valid DDMMYY Date of Birth, and this library does not currently check for this. At the moment, only the correct number range is checked for.

normalise_number()

Returns normalised 10-digit NHS Number without spaces, as a string.

Arguments:

  • nhs_number (required, str | int): The NHS Number int or str to normalise.
import nhs_number

nhs_number.normalise_number('123 456 7891')
# '1234567891'

nhs_number.normalise_number('1234567891')
# '1234567891'

nhs_number.normalise_number('123-456-7890')
# '1234567890'

generate()

Returns list of valid or invalid normalised NHS numbers, as strings, for testing.

By default numbers will be generated from any valid range, including ranges that are allocated for live patient use.

Arguments:

  • valid (optional, default=True, bool): Determines whether generated numbers are valid or invalid.
  • for_region (optional, default=None, Region): If provided, generates numbers within the given Region range.
  • quantity (optional, default=1, int): Determines number of NHS number strings returned.
import nhs_number

nhs_number.generate()
# ['1633104249']

nhs_number.generate(quantity=5)
# ['1633104249', '1633104257', '1633104265', '1633104273', '1633104281']

The for_region parameter takes any of the nhs_number.REGION_* constants:

nhs_number.generate(for_region=nhs_number.REGION_ENGLAND)
# ['7709030025']

Working with synthetic / unallocated numbers only

Careless use of numbers generated from this library could result in data loss, damage or compromise. You should never use numbers generated by this library in queries against live health service systems. If you want to avoid generating numbers which may have been allocated to real patients, apply the for_region=REGION_SYNTHETIC parameter to constrain the output of the function to only numbers from the 900000000n - 999999999n testing range.

NhsNumber object

For further details on the NHS number, including further Region-specific information, instantiate an NhsNumber object using a valid NHS number as a string:

from nhs_number import NhsNumber

nhs_number = NhsNumber('9876543210')

vars(nhs_number)
# {'nhs_number': '9876543210', 'identifier_digits': '987654321', 'check_digit': 0, 'valid': True, 'calculated_checksum': 0, 'region': <nhs_number.constants.Region object at 0x000001A0AD3CD490>, 'region_comment': 'Not to be issued (Synthetic/test patients PDS)'}

Regions

You can obtain Region objects via the package's REGION_* constants. See NHS Number Ranges for details on ranges.

Obtain a dictionary of available Range objects: 

import nhs_number

nhs_number.REGIONS
# {'UNALLOCATED': <nhs_number.constants.Region object at 0x7fda8e0b0e50>, 'SCOTLAND': <nhs_number.constants.Region object at 0x7fda8e0b0d10>, 'NORTHERN_IRELAND': <nhs_number.constants.Region object at 0x7fda8e0b0d90>, 'ENGLAND_WALES_IOM': <nhs_number.constants.Region object at 0x7fda8e0b0d50>, 'RESERVED': <nhs_number.constants.Region object at 0x7fda8e0b0e90>, 'EIRE': <nhs_number.constants.Region object at 0x7fda8e0b0dd0>, 'SYNTHETIC': <nhs_number.constants.Region object at 0x7fda8e0b0e10>}

Get a Region object for England: 

nhs_number.ENGLAND_WALES_IOM
# <nhs_number.constants.Region object at 0x7fda8e0b0d50>

Each Region has some aliases for ease of use: 

nhs_number.ENGLAND_WALES_IOM == nhs_number.REGION_ENGLAND
# True

Scottish CHI Number validation

At present, this library does not reliably validate Scottish CHI Numbers. This is because the first 6 digits of a Scottish CHI Number must be a valid DDMMYY Date of Birth, and this library does not currently check for this. At the moment, only the correct number range is checked for.