SSN::Validate - Perl extension to do SSN Validation
Index
Code Index:
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
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.
SEE ALSO
package SSN::Validate;
use 5.006;
use strict;
use warnings;
our $VERSION = '0.18';
# Preloaded methods go here.
# Data won't change, no need to _init() for every object
my $SSN = _init();
## "Within each area, the group number (middle two (2) digits)
## range from 01 to 99 but are not assigned in consecutive
## order. For administrative reasons, group numbers issued
## first consist of the ODD numbers from 01 through 09 and
## then EVEN numbers from 10 through 98, within each area
## number allocated to a State. After all numbers in group 98
## of a particular area have been issued, the EVEN Groups 02
## through 08 are used, followed by ODD Groups 11 through 99."
##
## ODD - 01, 03, 05, 07, 09
## EVEN - 10 to 98
## EVEN - 02, 04, 06, 08
## ODD - 11 to 99
my $GROUP_ORDER = [
'01', '03', '05', '07', '09', 10, 12, 14, 16, 18, 20, 22,
24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46,
48, 50, 52, 54, 56, 58, 60, 62, 64, 66, 68, 70,
72, 74, 76, 78, 80, 82, 84, 86, 88, 90, 92, 94,
96, 98, '02', '04', '06', '08', 11, 13, 15, 17, 19, 21,
23, 25, 27, 29, 31, 33, 35, 37, 39, 41, 43, 45,
47, 49, 51, 53, 55, 57, 59, 61, 63, 65, 67, 69,
71, 73, 75, 77, 79, 81, 83, 85, 87, 89, 91, 93,
95, 97, 99
];
my $ADVERTISING_SSN = [
'042103580',
'062360749',
'078051120',
'095073645',
128036045,
135016629,
141186941,
165167999,
165187999,
165207999,
165227999,
165247999,
189092294,
212097694,
212099999,
306302348,
308125070,
468288779,
549241889,
987654320,
987654321,
987654322,
987654323,
987654324,
987654325,
987654326,
987654327,
987654328,
987654329,
];
my $BAD_COMBO = [
55019,
58619,
58629,
58659,
58659,
58679..58699
];
sub new {
my ( $proto, $args ) = @_;
my $class = ref($proto) || $proto;
my $self = {};
bless( $self, $class );
$self->{'SSN'} = $SSN;
$self->{'GROUP_ORDER'} = $GROUP_ORDER;
$self->{'AD_SSN'} = $ADVERTISING_SSN;
$self->{'BAD_COMBO'} = $BAD_COMBO;
$self->{'BAD_COMBO_IGNORE'} = $args->{'ignore_bad_combo'} || 0;
return $self;
}
sub valid_ssn {
my ( $self, $ssn ) = @_;
$ssn =~ s!\D!!g;
if ( length $ssn != 9 ) {
$self->{'ERROR'} = "Bad SSN length";
return 0;
}
# Check for known invalid SSNs
# Start with Advertising SSNs. The SSA suggests the range of
# 987-65-4320 thru 987-65-4329 but these have also been used
# in ads.
if (in_array($ssn, $self->{'AD_SSN'})) {
$self->{'ERROR'} = 'Advertising SSN';
return 0;
}
my $area = substr( $ssn, 0, 3 );
my $group = substr( $ssn, 3, 2 );
my $serial = substr( $ssn, 5, 4 );
# Some groups are invalid with certain areas.
# Rhyme and reason are not a part of the SSA.
if (!$self->{'BAD_COMBO_IGNORE'} && in_array($area . $group, $self->{'BAD_COMBO'})) {
$self->{'ERROR'} = 'Invalid area/group combo';
return 0;
}
if ( !$self->valid_area($area) ) {
$self->{'ERROR'} = "Bad Area";
return 0;
}
elsif ( !$self->valid_group($ssn) ) {
$self->{'ERROR'} = "Bad Group";
return 0;
}
elsif ( !$self->valid_serial($serial) ) {
$self->{'ERROR'} = "Bad Serial";
return 0;
}
else {
return 1;
}
}
sub valid_area {
my ( $self, $area ) = @_;
$area = substr( $area, 0, 3) if length $area > 3;
return exists $self->{'SSN'}->{$area}->{valid} ? 1 : 0;
}
sub valid_group {
my ( $self, $group ) = @_;
$group =~ s!\D!!g;
#if ( length $group == 9 ) {
if ( length $group > 2 ) {
my $area = substr( $group, 0, 3 );
$group = substr( $group, 3, 2 );
return 0 if $group eq '00';
if (!$self->{'BAD_COMBO_IGNORE'} && in_array($area . $group, $self->{'BAD_COMBO'})) {
$self->{'ERROR'} = 'Invalid area/group combo';
return 0;
}
if ( defined $self->{'SSN'}{$area}{'highgroup'} ) {
# We're igno
if ($self->{'BAD_COMBO_IGNORE'} && in_array($area . $group, $self->{'BAD_COMBO'})) {
return 1;
}
return in_array( $group,
$self->get_group_range( $self->{'SSN'}{$area}{'highgroup'} ) );
}
elsif ( defined $self->{'SSN'}{$area}{'group_range'} ) {
return in_array( $group, $self->{'SSN'}{$area}{'group_range'} );
}
else {
return 1;
}
}
return $group eq '00' ? 0 : 1;
}
sub valid_serial {
my ( $self, $serial ) = @_;
return $serial eq '0000' ? 0 : 1;
}
sub get_state {
my ( $self, $ssn ) = @_;
my $area = substr( $ssn, 0, 3 );
if ( $self->valid_area($area) ) {
return defined $self->{'SSN'}->{$area}->{'state'}
? $self->{'SSN'}->{$area}->{'state'} : '';
}
else {
return '';
}
}
sub get_description {
my ( $self, $ssn ) = @_;
my $area = substr( $ssn, 0, 3 );
if ( $self->valid_area($area) ) {
return $self->{'SSN'}->{$area}->{'description'};
}
else {
return 0;
}
}
## given a high group number, generate a list of valid
## group numbers using that wild and carazy SSA algorithm.
sub get_group_range {
my ( $self, $highgroup ) = @_;
for ( my $i = 0 ; $i < 100 ; $i++ ) {
if (
sprintf( "%02d", $self->{'GROUP_ORDER'}[$i] ) ==
sprintf( "%02d", $highgroup ) )
{
return [ @{ $self->{'GROUP_ORDER'} }[ 0 .. $i + 1 ] ]; # array slice
}
}
return [];
}
sub in_array {
my ( $needle, $haystack ) = @_;
foreach my $hay (@$haystack) {
return 1 if $hay == $needle;
}
return 0;
}
sub _init {
my %by_ssn;
no warnings 'once';
# parse data into memory...
while (<DATA>) {
chomp;
# skip stuff that doesn't "look" like our data
next unless m/^[0-9]{3}/;
if (/^(\d{3}),(\d{2})\-*(\d*)\D*$/) {
if ( !defined $3 || $3 eq '' ) {
$by_ssn{$1}->{'highgroup'} = $2;
}
else {
if ( defined $by_ssn{$1}->{'group_range'} ) {
push @{ $by_ssn{$1}->{'group_range'} }, ( $2 .. $3 );
}
else {
$by_ssn{$1}->{'group_range'} = [ $2 .. $3 ];
}
}
next;
}
my ( $numeric, $state_abbr, $description ) = split /\s+/, $_, 3;
# deal with the numeric stuff...
$numeric =~ s/[^0-9,-]//; # sanitize for fun
# loop over , groups, if any...
for my $group ( split ',', $numeric ) {
# Skip over invalid ranges. Although they may be assigned
# if they are not yet issued, then no one has an area from
# it, so it is invalid by the SSA.
# May make a 'loose' bit to allow these to validate
next if $description =~ /not yet issued/i;
# pull apart hypened ranges
my ( $min, $max ) = split '-', $group;
# see whether a range to deal with exists...
if ( defined $max ) {
for my $number ( $min .. $max ) {
$by_ssn{$number} = {
'state' => $state_abbr,
'description' => $description,
'valid' => 1,
};
}
}
else {
$by_ssn{$min} = {
'state' => $state_abbr,
'description' => $description,
'valid' => 1,
};
}
}
}
return \%by_ssn;
}
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
# store SSN information inside the script down here...
#
# format is simple, three bits of data separated by tabs:
# numeric_range state_abbr description
#
# Leave state_abbr empty if not applicable. numeric_range consits
# of three-digit numbers, with -'s to denote ranges and ,'s to denote
# series of numbers or ranges.
__DATA__
001-003 NH New Hampshire
004-007 ME Maine
008-009 VT Vermont
010-034 MA Massachusetts
035-039 RI Rhode Island
040-049 CT Connecticut
050-134 NY New York
135-158 NJ New Jersey
159-211 PA Pennsylvania
212-220 MD Maryland
221-222 DE Delaware
223-231 VA Virginia
232 NC North Carolina
232-236 WV West Virginia
237-246 ?? Unknown
247-251 SC South Carolina
252-260 GA Georgia
261-267 FL Florida
268-302 OH Ohio
303-317 IN Indiana
318-361 IL Illinois
362-386 MI Michigan
387-399 WI Wisconsin
400-407 KY Kentucky
408-415 TN Tennessee
416-424 AL Alabama
425-428 MS Mississippi
429-432 AR Arkansas
433-439 LA Louisiana
440-448 OK Oklahoma
449-467 TX Texas
468-477 MN Minnesota
478-485 IA Iowa
486-500 MO Missouri
501-502 ND North Dakota
503-504 SD South Dakota
505-508 NE Nebraska
509-515 KS Kansas
516-517 MT Montana
518-519 ID Idaho
520 WY Wyoming
521-524 CO Colorado
525 NM New Mexico
585 NM New Mexico
526-527 AZ Arizona
528-529 UT Utah
530 NV Nevada
531-539 WA Washington
540-544 OR Oregon
545-573 CA California
574 AK Alaska
575-576 HI Hawaii
577-579 DC District of Columbia
580 VI Virgin Islands or Puerto Rico
581-584 PR Puerto Rico
#586 GU Guam
#586 AS American Somoa
#586 PI Philippine Islands
586 ?? Guam, American Samoa, or Philippine Islands
587 ?? Unknown
588 ?? New area allocated, but not yet issued
589-595 ?? Unknown
596-599 ?? Unknown
600-601 ?? Unknown
602-626 ?? Unknown
627-645 ?? Unknown
646-647 ?? Unknown
648-649 ?? Unknown
650-653 ?? New area allocated, but not yet issued
654-658 ?? Unknown
659-665 ?? New area allocated, but not yet issued
#666 ?? Unknown
667-675 ?? Unknown
676-679 ?? New area allocated, but not yet issued
680 ?? Unknown
681-690 ?? Unknown
691-699 ?? New area allocated, but not yet issued
700-728 RB Railroad Board (discontinued July 1, 1963)
750-751 ?? New area allocated, but not yet issued
752-755 ?? New area allocated, but not yet issued
756-763 ?? New area allocated, but not yet issued
764-899 ?? Unknown
#765 ?? Unknown
900-999 ?? Taxpayer Identification Number
## high groups
# This is scraped directly from
# http://www.socialsecurity.gov/employer/ssns/highgroup.txt
001,08
002,06
003,06
004,11
005,11
006,08
007,08
008,92
009,92
010,92
011,92
012,92
013,92
014,92
015,92
016,92
017,92
018,92
019,92
020,92
021,90
022,90
023,90
024,90
025,90
026,90
027,90
028,90
029,90
030,90
031,90
032,90
033,90
034,90
035,74
036,72
037,72
038,72
039,72
040,13
041,13
042,13
043,13
044,13
045,13
046,13
047,11
048,11
049,11
050,98
051,98
052,98
053,98
054,98
055,98
056,98
057,98
058,98
059,98
060,98
061,98
062,98
063,98
064,98
065,98
066,98
067,98
068,98
069,98
070,98
071,98
072,98
073,98
074,98
075,98
076,98
077,98
078,98
079,98
080,98
081,98
082,98
083,98
084,98
085,98
086,98
087,98
088,98
089,98
090,96
091,96
092,96
093,96
094,96
095,96
096,96
097,96
098,96
099,96
100,96
101,96
102,96
103,96
104,96
105,96
106,96
107,96
108,96
109,96
110,96
111,96
112,96
113,96
114,96
115,96
116,96
117,96
118,96
119,96
120,96
121,96
122,96
123,96
124,96
125,96
126,96
127,96
128,96
129,96
130,96
131,96
132,96
133,96
134,96
135,21
136,21
137,21
138,21
139,21
140,21
141,21
142,21
143,21
144,21
145,21
146,21
147,19
148,19
149,19
150,19
151,19
152,19
153,19
154,19
155,19
156,19
157,19
158,19
159,84
160,84
161,84
162,84
163,84
164,84
165,84
166,84
167,84
168,84
169,84
170,84
171,84
172,84
173,84
174,84
175,84
176,84
177,84
178,84
179,84
180,84
181,84
182,84
183,84
184,84
185,84
186,84
187,84
188,84
189,84
190,84
191,84
192,84
193,84
194,84
195,84
196,84
197,84
198,84
199,84
200,84
201,84
202,84
203,84
204,84
205,84
206,84
207,84
208,82
209,82
210,82
211,82
212,83
213,83
214,83
215,83
216,83
217,83
218,83
219,83
220,81
221,08
222,06
223,99
224,99
225,99
226,99
227,99
228,99
229,99
230,99
231,99
232,55
233,55
234,55
235,53
236,53
237,99
238,99
239,99
240,99
241,99
242,99
243,99
244,99
245,99
246,99
247,99
248,99
249,99
250,99
251,99
252,99
253,99
254,99
255,99
256,99
257,99
258,99
259,99
260,99
261,99
262,99
263,99
264,99
265,99
266,99
267,99
268,15
269,15
270,15
271,15
272,15
273,15
274,15
275,15
276,15
277,13
278,13
279,13
280,13
281,13
282,13
283,13
284,13
285,13
286,13
287,13
288,13
289,13
290,13
291,13
292,13
293,13
294,13
295,13
296,13
297,13
298,13
299,13
300,13
301,13
302,13
303,35
304,33
305,33
306,33
307,33
308,33
309,33
310,33
311,33
312,33
313,33
314,33
315,33
316,33
317,33
318,08
319,08
320,08
321,08
322,08
323,08
324,08
325,08
326,08
327,08
328,08
329,08
330,08
331,08
332,08
333,08
334,08
335,08
336,08
337,08
338,08
339,08
340,06
341,06
342,06
343,06
344,06
345,06
346,06
347,06
348,06
349,06
350,06
351,06
352,06
353,06
354,06
355,06
356,06
357,06
358,06
359,06
360,06
361,06
362,37
363,35
364,35
365,35
366,35
367,35
368,35
369,35
370,35
371,35
372,35
373,35
374,35
375,35
376,35
377,35
378,35
379,35
380,35
381,35
382,35
383,35
384,35
385,35
386,35
387,31
388,31
389,31
390,31
391,31
392,31
393,29
394,29
395,29
396,29
397,29
398,29
399,29
400,71
401,69
402,69
403,69
404,69
405,69
406,69
407,69
408,99
409,99
410,99
411,99
412,99
413,99
414,99
415,99
416,65
417,65
418,63
419,63
420,63
421,63
422,63
423,63
424,63
425,99
426,99
427,99
428,99
429,99
430,99
431,99
432,99
433,99
434,99
435,99
436,99
437,99
438,99
439,99
440,25
441,25
442,25
443,25
444,25
445,25
446,25
447,23
448,23
449,99
450,99
451,99
452,99
453,99
454,99
455,99
456,99
457,99
458,99
459,99
460,99
461,99
462,99
463,99
464,99
465,99
466,99
467,99
468,53
469,53
470,53
471,53
472,53
473,51
474,51
475,51
476,51
477,51
478,39
479,39
480,39
481,39
482,39
483,39
484,37
485,37
486,27
487,27
488,27
489,27
490,27
491,27
492,27
493,27
494,27
495,25
496,25
497,25
498,25
499,25
500,25
501,35
502,33
503,43
504,41
505,55
506,55
507,53
508,53
509,29
510,29
511,29
512,29
513,29
514,29
515,29
516,47
517,45
518,83
519,81
520,57
521,99
522,99
523,99
524,99
525,99
526,99
527,99
528,99
529,99
530,99
531,65
532,65
533,65
534,65
535,65
536,65
537,65
538,65
539,65
540,77
541,77
542,77
543,77
544,75
545,99
546,99
547,99
548,99
549,99
550,99
551,99
552,99
553,99
554,99
555,99
556,99
557,99
558,99
559,99
560,99
561,99
562,99
563,99
564,99
565,99
566,99
567,99
568,99
569,99
570,99
571,99
572,99
573,99
574,55
575,99
576,99
577,49
578,47
579,47
580,39
581,99
582,99
583,99
584,99
585,99
586,63
587,99
588,05
589,99
590,99
591,99
592,99
593,99
594,99
595,99
596,88
597,88
598,86
599,86
600,99
601,99
602,75
603,75
604,75
605,75
606,75
607,75
608,73
609,73
610,73
611,73
612,73
613,73
614,73
615,73
616,73
617,73
618,73
619,73
620,73
621,73
622,73
623,73
624,73
625,73
626,73
627,19
628,19
629,19
630,19
631,19
632,19
633,19
634,19
635,19
636,19
637,19
638,17
639,17
640,17
641,17
642,17
643,17
644,17
645,17
646,08
647,06
648,50
649,48
650,52
651,52
652,52
653,52
654,32
655,30
656,30
657,30
658,30
659,18
660,18
661,18
662,18
663,18
664,18
665,16
667,40
668,40
669,40
670,40
671,40
672,40
673,40
674,40
675,38
676,18
677,16
678,16
679,16
680,08
681,18
682,18
683,18
684,18
685,16
686,16
687,16
688,16
689,16
690,16
691,12
692,10
693,10
694,10
695,10
696,10
697,10
698,10
699,10
700,18
701,18
702,18
703,18
704,18
705,18
706,18
707,18
708,18
709,18
710,18
711,18
712,18
713,18
714,18
715,18
716,18
717,18
718,18
719,18
720,18
721,18
722,18
723,18
724,28
725,18
726,18
727,10
728,14
729,16
730,16
731,16
732,16
733,14
750,12
751,12
752,05
753,03
754,03
755,03
756,09
757,09
758,09
759,07
760,07
761,07
762,07
763,07
764,02
765,02
766,80
767,80
768,78
769,78
770,78
771,78
772,78
900,70-80 ## Individual Taxpayer Identification Number
900,93-93 ## Adoption Taxpayer Identification Number