Global

Methods

parse(idNumber) → {ValidIDParseResult|InvalidIDParseResult}

Validates and ID number and parses out all information from it.

This is a combination of the other parsing and validation functions, so refer to their documentation for any details.

Parameters:
Name Type Description
idNumber string

The ID number to be parsed.
Source:
Returns:

An object with all of the parsing results. If the ID is invalid, the result is an object with just an isValid property set to false.

Type
ValidIDParseResult | InvalidIDParseResult
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';

var info = saIdParser.parse(validIdNumber);
// info === {
//   isValid: true,
//   dateOfBirth: new Date(1990, 0, 4),
//   isMale: true,
//   isFemale: false,
//   isSouthAfricanCitizen: true
// }

var invalidIdNumber = '1234567';
info = saIdParser.parse(invalidIdNumber);
// info === {
//   isValid: false
// }

parseDateOfBirth(idNumber) → (nullable) {Date}

Parses the date of birth out of an ID number.

Minimal validation of the ID number is performed, requiring only that it's 13 digits long.

The date of birth included in the ID number has a two digit year. For example, 90 instead of 1990. This is converted to a full date by comparing the date of birth to the current date, and choosing the century that gives the person the lowest age, while still putting their age in the past.

For example, assuming that the current date is 10 December 2015. If the date of birth parsed is 10 December 15, it will be interpreted as 10 December 2015. If, on the other hand, the date of birth is parsed as 11 December 15, that will be interpreted as 10 December 1915.

The date will be in the local timezone, with the time portion set to midnight.

Parameters:
Name Type Description
idNumber string

The ID number to be parsed.
Source:
Returns:

The date of birth from the ID number, or undefined if the ID number is not formatted correctly or does not have a valid date of birth.

Type
Date
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';
var dateOfBirth = saIdParser.parseDateOfBirth(validIdNumber);

// dateOfBirth === new Date(1990, 0, 4)

parseIsFemale(idNumber) → (nullable) {bool}

Parses the sex out of the ID number and returns true it is female.

Minimal validation of the ID number is performed, requiring only that it's 13 digits long.

Parameters:
Name Type Description
idNumber string

The ID number to be parsed.
Source:
Returns:

True if female, false if male. Returns undefined if the ID number is not a 13 digit number.

Type
bool
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';
var isFemale = saIdParser.parseIsFemale(validIdNumber);

// isFemale === false

parseIsMale(idNumber) → (nullable) {bool}

Parses the sex out of the ID number and returns true it is male.

Minimal validation of the ID number is performed, requiring only that it's 13 digits long.

Parameters:
Name Type Description
idNumber string

The ID number to be parsed.
Source:
Returns:

True if male, false if female. Returns undefined if the ID number is not a 13 digit number.

Type
bool
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';
var isMale = saIdParser.parseIsMale(validIdNumber);

// isMale === true

parseIsSouthAfricanCitizen(idNumber) → (nullable) {bool}

Parses the citizenship status out of an ID number and returns true if it indicates South African citizen.

Minimal validation of the ID number is performed, requiring only that it's 13 digits long.

Parameters:
Name Type Description
idNumber string

The ID number to be parsed.
Source:
Returns:

True if the ID number belongs to a South African citizen. Returns undefined if the ID number is not a 13 digit number.

Type
bool
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';
var isSouthAfricanCitizen = saIdParser.parseIsSouthAfricanCitizen(validIdNumber);

// isSouthAfricanCitizen === true

validate(idNumber) → {bool}

Validates an ID number.

This includes making sure that it follows the expected 13 digit pattern, checking that the control digit is correct, and checking that the date of birth is a valid date.

Parameters:
Name Type Description
idNumber string

The ID number to be validated.
Source:
Returns:

True if the ID number is a valid South African ID number.

Type
bool
Example
var saIdParser = require('south-african-id-parser');
var validIdNumber = '9001049818080';
var isValid = saIdParser.validate(validIdNumber);

// valid === true

Type Definitions

InvalidIDParseResult

Parsing result for a invalid South African ID number.

Type:
  • Object
Properties:
Name Type Description
isValid bool

false
Source:

ValidIDParseResult

Parsing result for a valid South African ID number.

Type:
  • Object
Properties:
Name Type Description
isValid bool

true
dateOfBirth Date

The date of birth from the ID number.
isMale bool

The sex from the ID number - true if male, false if female.
isFemale bool

The sex from the ID number - true if female, false if male.
isSouthAfricanCitizen bool

Citizenship status from the ID number, true if it indicates South African citizenship.
Source: