Format

Generates values in published identifier formats, such as credit card numbers, IBANs, ISBNs, and national insurance and tax numbers. Each value passes the validation its format defines.

Formats with a check digit use the published algorithm for it, such as Luhn for credit card numbers and mod-97 for IBANs. Formats without a check digit, such as SSN and EIN, follow the documented structure of each part of the number. Formats that encode a date of birth, such as a Swedish personnummer or a Polish PESEL, contain a real calendar date, with any century or sex marker the format defines. Generated values are valid in form only. They are not issued, and do not correspond to real cards, accounts or people.

Use this field for columns that the receiving system validates, such as a card number checked with the Luhn algorithm or an IBAN whose check digits are verified on import. A random string of the correct length fails that validation.

For values that only need to be unique within the data set, such as GUIDs or reference codes, use Identifier.

Driver's license numbers are not available as modes. Their format varies by jurisdiction, and many encode the holder's surname and date of birth. Build them with derivedId on a Person field, which supports surname extraction, date components, sex offsets, phonetic encodings and check characters. For a license format that encodes no personal data, use an Identifier pattern.

Sub-field: value

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Properties

Property	Type	Default	Description
`creditCardBinPrefix`	`string`	none	A numeric issuer prefix, used instead of the network's own prefix. Requires `creditCardLength`.
`creditCardLength`	`integer`	none	The total card number length. Required with `creditCardBinPrefix`, and must be longer than the prefix. Ignored otherwise.
`creditCardNetworks`	`string[]`	none	The networks to use: `Visa`, `Mastercard`, `Amex` or `Discover`. Each row uses one of them, which sets the prefix and length. With no list, each row uses one of the four. Ignored when `creditCardBinPrefix` is set.
`einPrefixes`	`string[]`	none	The 2-digit prefixes to use. Each row uses one of them. With no list, the prefix is any prefix the IRS assigns. A prefix the IRS does not assign, such as `07` or `89`, is rejected.
`ibanCountryCodes`	`string[]`	none	The 2-letter ISO country codes to use. Each row uses one of them. With no list, each row uses any country with a built-in IBAN format.
`ibanLength`	`integer`	none	The total IBAN length, used for every country in `ibanCountryCodes`. Required for a country with no built-in IBAN length. Must be from 5 to 34.
`ipv4Cidr`	`string`	none	A CIDR range, such as `10.0.0.0/8`. The network bits are fixed and the host bits are random. With no range, any IPv4 address is used.
`ipv6Cidr`	`string`	none	The same as `ipv4Cidr`, for IPv6, such as `fd00::/8`.
`macAddressOuiPrefix`	`string`	none	A fixed 3-octet vendor prefix, such as `00:1A:2B`. Only the last 3 octets are random. With no prefix, the address is a random locally administered unicast address.
`map`	`object`	required	Maps the `value` sub-field to a destination column, which must be a text column: `VarChar`, `Char` or `Clob`. See Building a Request.
`mode`	see Modes	required	The format to generate. See Modes.
`nullPercentageMax`	`number`	`0`	Upper bound (0-100) of the percentage of rows that should be null. See `nullPercentageMin`.
`nullPercentageMin`	`number`	`0`	Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to `nullPercentageMax` for an exact rate.
`seed`	`integer`	random	Per-field seed, overriding the request's own `seed` for this field only.
`ssnAreaCodes`	`integer[]`	none	The 3-digit area numbers to use, each from 1 to 899, excluding 666. Each row uses one of them. With no list, the area is any valid area number.
`unique`	`boolean`	`false`	Whether every generated value must differ from the others. Limited by the number of values the format can produce. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

Modes

mode sets the format, and is required. Each mode either applies the format's published check-digit algorithm or, for a format with no check digit, follows its documented structure.

Several modes have properties that limit their values, for example to one card network or to IBANs from one country. See Limiting a mode.

Properties by mode

Each property below applies only to the modes listed for it, and is ignored in any other mode.

Property	Modes
`creditCardNetworks`, `creditCardBinPrefix`, `creditCardLength`	`CreditCard`
`ibanCountryCodes`, `ibanLength`	`Iban`
`ipv4Cidr`	`Ipv4`
`ipv6Cidr`	`Ipv6`
`macAddressOuiPrefix`	`MacAddress`
`ssnAreaCodes`	`Ssn`
`einPrefixes`	`Ein`
`nullPercentageMin`, `nullPercentageMax`	every mode
`unique`, `seed`	every mode

Letters are upper case in every mode except Ipv6, which is written in lower case.

Payment and finance

Mode	Produces
`AbaRoutingNumber`	A checksum-valid 9-digit US ABA routing number.
`CreditCard`	A Luhn-valid credit or debit card number.
`Cusip`	A check-digit-valid 9-character CUSIP, a US and Canadian securities identifier.
`Iban`	A mod-97-valid IBAN.
`Isin`	A Luhn-valid ISIN: a country code, a 9-character alphanumeric NSIN and a check digit.
`Lei`	A mod-97-valid 20-character Legal Entity Identifier (ISO 17442).
`Sedol`	A check-digit-valid 7-character SEDOL, a UK and Irish securities identifier.

Products and publishing

Mode	Produces
`Ean13`	A check-digit-valid 13-digit EAN-13 barcode number.
`Ean8`	A check-digit-valid 8-digit EAN-8 barcode number.
`Gtin14`	A check-digit-valid GTIN-14 (ITF-14) barcode number.
`Isbn10`	A check-digit-valid ISBN-10.
`Isbn13`	A check-digit-valid ISBN-13, with a 978 prefix, or a 979 prefix followed by 8, 10, 11 or 12.
`Ismn`	A check-digit-valid ISMN, with the 979-0 prefix.
`Issn`	A check-digit-valid ISSN, formatted `XXXX-XXXX`.
`Upc`	A check-digit-valid 12-digit UPC-A barcode number.

Devices and networks

Mode	Produces
`Imei`	A Luhn-valid 15-digit IMEI.
`Ipv4`	An IPv4 address in dotted-quad form.
`Ipv6`	An IPv6 address.
`MacAddress`	A MAC-48 address, locally administered and unicast unless `macAddressOuiPrefix` is set.

National identity, tax and health

Mode	Produces
`BulgarianEgn`	A weighted-mod-11-valid 10-digit Bulgarian EGN, with a birth date.
`CanadianSin`	A Luhn-valid Canadian Social Insurance Number.
`Cnpj`	A check-digit-valid Brazilian CNPJ, formatted `XX.XXX.XXX/XXXX-XX`.
`Cpf`	A check-digit-valid Brazilian CPF, formatted `XXX.XXX.XXX-XX`.
`CzechBirthNumber`	A Czech or Slovak birth number divisible by 11, with a birth date, formatted `YYMMDD/XXXX`.
`DutchBsn`	An 11-proof-valid 9-digit Dutch BSN.
`Ein`	A US Employer Identification Number, formatted `XX-XXXXXXX`, with a prefix the IRS assigns. An EIN has no check digit.
`FinnishHetu`	A mod-31-valid Finnish henkilötunnus, with a birth date, formatted `DDMMYY-ZZZC`, with `A` in place of `-` for a birth in the 2000s.
`FrenchNir`	A mod-97-valid 15-digit French INSEE (NIR) number, with a birth year and month and a department.
`GermanTaxId`	A check-digit-valid German tax identification number (ISO 7064 MOD 11,10).
`IndianAadhaar`	A Verhoeff-checksum-valid 12-digit Aadhaar number, in groups of 4.
`NorwegianFodselsnummer`	A dual-mod-11-valid 11-digit Norwegian fødselsnummer, with a birth date.
`Npi`	A Luhn-valid US National Provider Identifier.
`PassportNumber`	A 9-character alphanumeric passport number and its ICAO 9303 check digit, 10 characters in all, as the number is written in a passport's machine-readable zone.
`PolishPesel`	A weighted-mod-10-valid 11-digit Polish PESEL, with a birth date.
`PortugueseNif`	A weighted-mod-11-valid 9-digit Portuguese NIF.
`SpanishDniNie`	A mod-23-valid Spanish DNI or NIE, formatted `XXXXXXXXL`.
`Ssn`	A US Social Security Number. An SSN has no check digit.
`SwedishPersonnummer`	A Luhn-valid 10-digit Swedish personnummer, with a birth date, formatted `YYMMDD-XXXC`.
`TurkishKimlikNo`	A checksum-valid 11-digit Turkish TC Kimlik No.
`UkNhsNumber`	A check-digit-valid UK NHS number.

The same seed produces the same values in every mode.

Limiting a mode

Most modes have no properties of their own. These modes accept a property that limits their values to one issuer, country, network or address range:

Mode	Property	Effect
`CreditCard`	`creditCardNetworks`	Limits the numbers to one or more of `Visa`, `Mastercard`, `Amex` and `Discover`. The network sets the prefix and length.
`CreditCard`	`creditCardBinPrefix` with `creditCardLength`	Sets an exact issuer prefix, used instead of the network's prefix. Both are required together.
`Iban`	`ibanCountryCodes`	Limits the IBANs to one or more countries. Each country has its own length and structure.
`Iban`	`ibanLength`	Sets the length, which is needed only for a country with no built-in IBAN length.
`Ssn`	`ssnAreaCodes`	Limits the 3-digit area number.
`Ein`	`einPrefixes`	Limits the 2-digit prefix, which identifies the issuing campus.
`Ipv4`	`ipv4Cidr`	Limits the addresses to a CIDR range.
`Ipv6`	`ipv6Cidr`	The same, for IPv6.
`MacAddress`	`macAddressOuiPrefix`	Sets the 3-octet vendor prefix, so only the rest is random.

Where a property takes a list, each row uses one entry from it, so a list of three networks produces a mix of all three.

Without the property, the mode uses every valid value of the format.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request, not a complete request on its own. See Building a Request for how it fits into a full DatasetRequest.

A Visa or Mastercard number

{
  "type": "Format",
  "mode": "CreditCard",
  "creditCardNetworks": ["Visa", "Mastercard"],
  "map": { "value": { "column": "card_number", "dataType": "VarChar" } }
}

Sample output:

card_number
5392054569751060
4648133772575485
5291094192678878
4027191020272959
5508046907744550
5389055728626189

A German or French IBAN

{
  "type": "Format",
  "mode": "Iban",
  "ibanCountryCodes": ["DE", "FR"],
  "map": { "value": { "column": "iban", "dataType": "VarChar" } }
}

Sample output:

iban
DE47244514095082557914
DE34601383057128037590
FR3646354804429PI160IH7VW83
DE08335748862426229647
DE70637071725624125495
DE65683468558591503666

A mode with no other properties

Most modes need only mode.

{
  "type": "Format",
  "mode": "Isbn13",
  "seed": 11,
  "map": { "value": { "column": "isbn", "dataType": "VarChar" } }
}

Sample output:

isbn
9780491189330
9780116948953
9785887635590
9783724218227

A national identifier

{
  "type": "Format",
  "mode": "UkNhsNumber",
  "seed": 1,
  "map": { "value": { "column": "nhs_number", "dataType": "VarChar" } }
}

Sample output:

nhs_number
2147643912
6023966268
7790137174
3885760983

A card from one issuer

creditCardBinPrefix with creditCardLength sets the prefix instead of a network.

{
  "type": "Format",
  "mode": "CreditCard",
  "creditCardBinPrefix": "453201",
  "creditCardLength": 16,
  "map": { "value": { "column": "card_number", "dataType": "VarChar" } }
}

Sample output:

card_number
4532018226154814
4532019552229444
4532014596203638
4532017118484370
4532019756756515
4532017648608423

Every number starts with the same six digits and is Luhn-valid.

A MAC address from one vendor

{
  "type": "Format",
  "mode": "MacAddress",
  "macAddressOuiPrefix": "00:1A:2B",
  "map": { "value": { "column": "mac_address", "dataType": "VarChar" } }
}

Sample output:

mac_address
00:1A:2B:D8:40:11
00:1A:2B:53:C6:D1
00:1A:2B:9C:51:05
00:1A:2B:13:18:2B
00:1A:2B:04:CC:2E
00:1A:2B:1B:C4:37

A private-network IPv4 address

{
  "type": "Format",
  "mode": "Ipv4",
  "ipv4Cidr": "10.0.0.0/8",
  "map": { "value": { "column": "ip_address", "dataType": "VarChar" } }
}

Sample output:

ip_address
10.243.200.114
10.101.117.161
10.54.176.35
10.96.122.210
10.97.158.185
10.168.60.63

A unique local IPv6 address

{
  "type": "Format",
  "mode": "Ipv6",
  "ipv6Cidr": "fd00::/8",
  "seed": 1,
  "map": { "value": { "column": "ip_address", "dataType": "VarChar" } }
}

Sample output:

ip_address
fdd0:8682:4097:e4a3:95cf:ff46:699c:73c4
fdcd:1034:135b:4ea3:6f84:a54a:df7a:ea0
fde3:c117:6ce4:8e82:4e02:21be:f3b:5358
fda3:2818:4be9:91eb:81e3:12bc:f19a:c41a

Null rows

{
  "type": "Format",
  "mode": "Iban",
  "ibanCountryCodes": ["GB"],
  "nullPercentageMin": 20,
  "nullPercentageMax": 20,
  "seed": 2,
  "map": { "value": { "column": "iban", "dataType": "VarChar" } }
}

Sample output:

iban
GB30EZCH84207005327270

GB96TXVQ90699103867600
GB08MZOA43466085404026
GB38NCUY91559560808737

Table of Contents

Format

Properties

Modes

Properties by mode

Payment and finance

Products and publishing

Devices and networks

National identity, tax and health

Limiting a mode

Examples

A Visa or Mastercard number

A German or French IBAN

A mode with no other properties

A national identifier

A card from one issuer

A MAC address from one vendor

A private-network IPv4 address

A unique local IPv6 address

Null rows