NAME

SSN::Validate - Perl extension to do SSN Validation

SYNOPSIS

  use SSN::Validate;
  my $ssn = new SSN::Validate;
  or 
  my $ssn = SSN::Validate->new({'ignore_bad_combo' => 1});
  if ($ssn->valid_ssn("123-45-6789")) {
    print "It's a valid SSN";
  }
  my $state = $ssn->get_state("123456789");     
  my $state = $ssn->get_state("123");   
        print $ssn->valid_area('123') ? "Valid" : "Invalid";
        print $ssn->valid_area('123-56-7890') ? "Valid" : "Invalid";

DESCRIPTION

This module is intented to do some Social Security Number validation (not verification) beyond just seeing if it contains 9 digits and isn't all 0s. The data is taken from the Social Security Admin. website, specifically:

http://www.ssa.gov/foia/stateweb.html

As of this initial version, SSNs are validated by ensuring it is 9 digits, the area, group and serial are not all 0s, and that the area is within a valid range used by the SSA.

It will also return the state which the SSN was issues, if that data is known (state of "??" for unknown states/regions).

A SSN is formed by 3 parts, the area (A), group (G) and serial (S):

AAAA-GG-SSSS

METHODS

new();: You can pass an arg of 'ignore_bad_combo' as true if you wish to ignore any defined bad AAAA-GG combinations. Things will be on the list until I see otherwise on the SSA website or some other means of proof.

valid_ssn($ssn);: The SSN can be of any format (111-11-1111, 111111111, etc...). All non-digits are stripped.
This method will return true if it is valid, and false if it isn't. It uses the below methods to check the validity of each section.

valid_area($ssn);: This will see if the area is valid by using the ranges in use by the SSA. You can pass this method a full SSN, or just the 3 digit area.

valid_group($group);: Will make sure that the group isn't "00", as well as check the AREA/GROUP combo for known invalid ones, and the SSA High Groups.
If given a 2 digit GROUP, it will only make sure that that GROUP isn't "00".
If given a number in length above 2 digits, it will attempt to split into an AREA and GROUP and do further validation.

valid_serial($serial);: This is currently only making sure the serial isn't "0000", and that's all it will ever do. From my reading, "0000" is the only non-valid serial.
This is also semi-useful right now, as it expects only 4 digits. Later it will take both 4 digits or a full serial.

get_state($ssn);: You can give this a full SSN or 3 digit area. It will return the state, if known, from where the given area is issued. Invalid areas will return false.

get_description($ssn);: If there is a description associated with the state or region, this will return it.. or will return an empty string.

TODO

* Change how the data is stored. I don't like how it is done now... but works.

* Find out state(s) for areas which aren't known right now.

* Automate this module almost as completely as possible for
distribution.

* Consider SSN::Validate::SSDI for Social Security Death Index (SSDI)

* Possibly change how data is stored (first on TODO), and provide my extract script for people to run on their own. This way, maybe they could update the SSA changes on their own, instead of being dependant on the module for this, or having to update the module when the SSA makes changes. I think I like this idea.

EXPORT

None by default.

BUGS

Please let me know if something doesn't work as expected.

You can report bugs via the CPAN RT: <http://rt.cpan.org/NoAuth/Bugs.html?Dist=SSN-Validate>

If you are feeling nice, and would like quicker fixes, please provide a diff against Validate.pm and the appropriate test file(s). If you are making something invalid which is currently valid, or vice versa, please provide a reference to why the change is needed. Thanks!

Patches Welcome!

AUTHOR

Kevin Meltzer, <kmeltz@cpan.org>

LICENSE

SSN::Validate is free software which you can redistribute and/or modify it under the same terms as Perl itself.