iin-bin

Validate and parse Kazakhstan IIN (Individual Identification Number) and BIN (Business Identification Number) — the 12-digit identifiers used for individuals and legal entities in Kazakhstan.

What is IIN/BIN?

Features

• Full checksum validation (two-stage mod-11 algorithm)
• Automatic IIN vs BIN detection
• IIN: extracts gender, birth date, registration number
• BIN: extracts registration date, legal entity type, structural attribute
• TypeScript-first with full type definitions
• Zero dependencies
• ESM and CommonJS support

Install

npm install iin-bin

Usage

Parse (with validation)

import { parse } from "iin-bin";

const result = parse("780421334966");

if (result.type === "IIN") {
  result.gender; // "male"
  result.birthDate; // Date(1978-04-21)
  result.birthYear; // 1978
  result.birthMonth; // 4
  result.birthDay; // 21
  result.registrationNumber; // "3496"
}

if (result.type === "BIN") {
  result.registrationYear; // 14
  result.registrationMonth; // 12
  result.legalEntityType; // "resident"
  result.legalEntityAttribute; // "head-office"
}

Validate without throwing

import { isValid, validate } from "iin-bin";

isValid("780421334966"); // true
isValid("000000000000"); // false

const error = validate("123");
if (error) {
  error.code; // "INVALID_LENGTH"
  error.message; // "Expected 12 digits, got 3"
}

API

parse(value: string): ParseResult

Parses and validates a 12-digit IIN or BIN string. Throws IINBINError if invalid.

Returns IINData or BINData depending on the detected type.

isValid(value: string): boolean

Returns true if the value is a valid IIN or BIN, false otherwise.

validate(value: string): IINBINError | null

Returns null if valid, or an IINBINError with a descriptive code and message.

Error codes

| Code | Description | | -------------------- | ----------------------------------------------- | | INVALID_LENGTH | Not exactly 12 characters | | INVALID_CHARACTERS | Contains non-digit characters | | INVALID_CHECKSUM | Fails control number verification | | INVALID_DATE | IIN contains an impossible date | | INVALID_STRUCTURE | Unexpected digit values in structural positions |

Types

type IINData = {
  value: string;
  type: "IIN";
  gender: "male" | "female";
  birthDate: Date;
  birthYear: number;
  birthMonth: number;
  birthDay: number;
  registrationNumber: string;
};

type BINData = {
  value: string;
  type: "BIN";
  registrationYear: number;
  registrationMonth: number;
  legalEntityType:
    | "resident"
    | "non-resident"
    | "individual-entrepreneur"
    | "reserved";
  legalEntityAttribute:
    | "head-office"
    | "branch-office"
    | "representative-office"
    | "isolated-structural-unit"
    | "peasant-farming"
    | null;
};

Development

npm install
npm test          # run tests
npm run build     # build for production
npm run typecheck # type-check without emitting

License

MIT