# stdnum.us.ssn

SSN (U.S. Social Security Number).

The Social Security Number is used to identify individuals for taxation purposes. It is a 9-digit number that consists of a 3-digit area number, a 2-digit group number and a 4-digit serial number. The number does not use a check digit.

Some validation options are available but with the introduction of Social Security Number Randomization it is no longer possible to validate using the High Group History List. Some areas, groups and ranges can be blacklisted though.

There are several on-line verification facilities available, either for Employers or at a fee but validation requires more information than just the number (e.g. name, date of birth, etc). Another means of validation is the Death Master File which can be ordered on DVD.

More information:

- https://en.wikipedia.org/wiki/Social_Security_number

- https://www.ssa.gov/employer/verifySSN.htm

- https://en.wikipedia.org/wiki/Death_Master_File

    >>> validate('536-90-4399')
    '536904399'
    >>> validate('1112-23333')  # dash in the wrong place
    Traceback (most recent call last):
        ...
    InvalidFormat: ...
    >>> validate('666-00-0000')  # invalid area
    Traceback (most recent call last):
        ...
    InvalidComponent: ...
    >>> validate('078-05-1120')  # blacklisted entry
    Traceback (most recent call last):
        ...
    InvalidComponent: ...
    >>> compact('1234-56-789')
    '123456789'
    >>> format('111223333')
    '111-22-3333'

stdnum.us.ssn.compact(number: str) → str

  Convert the number to the minimal representation. This strips the number of any valid separators and removes surrounding whitespace.

stdnum.us.ssn.format(number: str) → str

  Reformat the number to the standard presentation format.

stdnum.us.ssn.is_valid(number: str) → bool

  Check if the number is a valid SSN.

stdnum.us.ssn.validate(number: str) → str

  Check if the number is a valid SSN. This checks the length, groups and formatting if it is present.