Test Data Generator
REST API


Random key's Test Data Generator REST API is a static data masking tool. It's a REST API that returns realistic personal information in exchange for input data of the same type that was provided in the request. The app has a special capability of consistently producing the same output for the same input. The returned value is uniquely linked to the value in the requests, so that Joanna always returns Marilyn, and Smith always translates to O'Reilly. The translation pairs are randomly generated for each customer. Please consult the Roadmap page for planned release dates of new services.

Example POST request to the Test Data API's Name endpoint:

{
 "headers": {
  "auth": "51349d7defd9351ac",
  "Content-Type": "application/json"
 },
 "body": {
  "name": "Daniel",
  "gender": "m",
  "region": "uk"
 }
}

Example response:

SUPPORTED API MANAGERS

POSTMAN
Import the collection from the Postman client or read the documentation and run the API in Postman.

GENERAL API DOCUMENTATION

Authentication & Quota
To start using the app, you need to register with your email and get your unique authorization token. The token has to be included in all your REST requests. For a start every registered user gets 10,000 free requests.

Headers
Make sure to include the content type and the authentication token in your request headers:

{
 "headers": {
  "auth": "[your token]" ,
  "Content-Type": "application/json"
 }
}

Methods Reference
GET METHODS:
Quota

POST METHODS:
Integer, Double, Number, First Name, Last Name, Location, National Insurance Number, Social Security Number, Numéro de Sécurité Sociale, Internal Russian Passport - Паспорт гражданина Российской Федерации, Credit Card Number, Date of Birth, Date

SUPPORTED REGIONS

About Regions
Some methods, such as Names and Locations support localized responses. The region can be specified in the request body.
Available regions: United Kingdom, United States, France, Germany, Russia

UK
Country code: "uk"
Supports: Name, First Name, Last Name, Full Name, Location, NIN
The British dataset contains information from England, Scotland, Wales, and Nothern Ireland. The National Insurance Numbers are generated based on the HMRC specification for the NIN numbers. The location dataset comprises of 1,257,440 individual addresses in a format: city, country, postcode. Altogether there are ~1470 unique towns/cities.

US
Country code: "us"
Supports: Name, First Name, Last Name, Full Name, Location, SSN
The US location database includes ~20,000 unique incorporated locations as per census.gov (over 30,000 places if counting the postcodes), in a format: city, state, zip code. SSN numbers follow the SSA specification for Social Security Numbers.

FR
Country code: "fr"
Supports: Name, First Name, Last Name, Full Name, Location, SSN
The French dataset includes 35,000 places in France (mainland), in a format: city, post code. The Numéro de Sécurité Sociale numbers have been generated by following the INSEE specification for a valid NSS format.

DE
Country code: "de"
Supports: Name, First Name, Last Name, Full Name, Location
The German location database hosts ~20,000 addresses, returned in a format: postcode, city, state.

RU
Country code: "ru"
Supports: Name, First Name, Last Name, Full Name, Location, IRP
The Russian dataset includes the most common Russian names and surname, both differentiated by gender. There are ~10,000 unique locations, each location returned in a format: city, region, postcode. You can retrieve internal passport numbers for the region. The IDs are generated following the MIA of Russia's specification for valid passport numbers.

GET METHODS

Quota
Endpoint: https://test.api.randomkey.io/v1/quota
A GET method for checking the request quota.

POST METHODS

Integer
Endpoint: https://test.api.randomkey.io/v1/int
Requires: number (int), min (int), max (int)
Returns: number (int)
Unique: No
A POST method for retrieving an integer. The method is non-sign preserving and non-length preserving. For best results, specify the range that matches the maximum and minimum values that can occur in your original dataset.
This is how an example request body will look like:

{
 "number": -100,
 "min": -200,
 "max": 100
}


You will receive data in the following format:

{
 "number": -12
}

Double
Endpoint: https://test.api.randomkey.io/v1/double
Requires: number (double), min (double), max (double)
Returns: number (double)
Unique: No
A POST method for retrieving a double. The method is non-sign preserving and non-length preserving. For best results, specify the range that matches the maximum and minimum values that can occur in your original dataset.
This is how an example request body will look like:

{
 "number": 10.02,
 "min": 0.00,
 "max": 2000.05
}


You will receive data in the following format:

{
 "number": 1867.99
}

Number
Endpoint: https://test.api.randomkey.io/v1/number
Requires: number (string)
Returns: number (string)
Unique: No
A POST method for retireving a number of the specified length. The generated string may include leading zeros.
This is how an example request body will look like:

{
 "number": "1189007801"
}


You will receive data in the following format:

{
 "number": "0557459551"
}

First Name
Endpoint: https://test.api.randomkey.io/v1/name/first
Requires: name (string), gender (string), region (string)
Returns: name (string)
Unique: No
A POST method for retrieving a first name of the specified gender. The method is regional, i.e. the region has to be specified in the request's body. Consult the Supported Regions section for valid country codes.

Specify gender in the request as:
For female, use: "f"
For male, use: "m"

This is how an example request body will look like:

{
 "name": "Alexis",
 "gender": "m",
 "region": "fr"
}


You will receive data in the following format:

{
 "name": "François"
}

Last Name
Endpoint: https://test.api.randomkey.io/v1/name
Requires: name (string), gender (string), region (string)
Returns: name (string)
Unique: No
A POST method for retrieving last names. The method is regional, i.e. the region has to be specified in the request's body. Consult the Supported Regions section for valid country codes.

Specify gender in the request as:
For N/A, use: "0"
For female, use: "f"
For male, use: "m"

This is how an example request body will look like:

{
 "name": "Tennant",
 "gender": "0",
 "region": "uk"
}


You will receive data in the following format:

{
 "name": "Sanders"
}

Location
Endpoint: https://test.api.randomkey.io/v1/location
Requires: city (string), admin (string), zip (string), region (string)
Returns: city (string), admin (string), zip (string)
Unique: No
A POST method for retrieving a location. The request requires 3 values to be provided: city, admin (the administrative body the location belongs to, for US that's a state, for UK that's a country), and zip (post code). In cases the state or zip are unknown provide an empty string in the value or choose a static value. The method is regional, i.e. the region has to be specified in the request's body. Consult the Supported Regions section for valid country codes.
This is how an example request body for the US region will look like:

{
 "city": "O'Fallon",
 "admin": "Missouri",
 "zip": "63366",
 "region": "us"
}


You will receive data in the following format:

{
 "city": "Mountain Brook",
 "admin": "Alabama",
 "zip": "35216"
}

This is how an example request body for the UK region and with empty admin and zip fields will look like:

{
 "city": "London",
 "admin": "",
 "zip": "",
 "region": "uk"
}


You will receive data in the following format:

{
 "city": "Brighton",
 "admin": "England",
 "zip": "BN2 0GQ"
}

National Insurance Number
Endpoint: https://test.api.randomkey.io/v1/id/nin
Requires: id (string)
Returns: id (string)
Unique: No
A POST method for retrieving British National Insurance Numbers. The generated NIN numbers follow the HMRC specification for a valid NIN format.
This is how an example request body will look like:

{
 "id": "KR118911D"
}


You will receive data in the following format:

{
 "id": "CK899677C"
}

Social Security Number
Endpoint: https://test.api.randomkey.io/v1/id/ssn
Requires: ssn (string)
Returns: ssn (string)
Unique: No
A POST method for retrieving Social Security Numbers (US only). The generated SSN numbers follow the SSA specification for a valid SSN format.
This is how an example request body will look like:

{
 "id": "741965201"
}


You will receive data in the following format:

{
 "id": "290663763"
}

Numéro de Sécurité Sociale
Endpoint: https://test.api.randomkey.io/v1/id/nss
Requires: id (string), gender (string)
Returns: id (string), dob (string)
A POST method for retrieving French social security number, i.e. numéro de sécurité sociale. The method returns a Date of Birth based on the information derived from the NSS. The NSS numbers have been generated by following the INSEE specification for a valid NSS format. You can specify the gender in the request:
For a female NSS, use: "f"
For a male NSS, use: "m"
For a random NSS, use: "0"

This is how an example request will look like:

{
 "id": "107059910504824",
 "gender": "m"
}


You will receive data in the following format:

{
 "id": "176072520223835",
 "dob": "18/07/86"
}

Internal Russian Passport
Endpoint: https://test.api.randomkey.io/v1/id/irp
Requires: records (int)
Returns: id (string)
A POST method for retrieving internal Russian passport number, i.e. Паспорт гражданина Российской Федерации. The numbers have been generated by following the MIA of Russia's specification for valid passport numbers.

This is how an example request will look like:

{
 "id": "2460274745"
}


You will receive data in the following format:

{
 "id": [
  [
   "0863452592"
  ]
 ]
}

Credit Card Number
Endpoint: https://test.api.randomkey.io/v1/ccn
Requires: ccn (string)
Returns: ccn (string)
Unique: No
A POST method for retrieving Payment Card Numbers. The pool of supported IIN's includes the biggest financial institutions issuing credit and debit cards: American Express, Diners Club, China UnionPay, VISA, MasterCard, Maestro, and Discover. The PANs generated follow the structure supported by their vendor, e.g. a returned American Express card would have exactly 15 digits. Each number passes the Luhn check and carries the Luhn digit. As a security precaution, use hashed or otherwise protected PANs in your requests. Note: The numbers generated are not unique, but a chance of a repeated value is negligible. For example, a chance to generate the same 16 digit value for various inputs is 1 in 249,999,999,999,999,750,000.

This is how an example request body will look like:

{
 "ccn": "3004772840621019"
}


You will receive data in the following format:

{
 "ccn": "576359251352186493"
}

Date of Birth
Endpoint: https://test.api.randomkey.io/v1/dob
Requires: format (string), date (string)
Returns: date (string)
Unique: No

A POST method for retrieving a realistic date - traditionally used for dates of birth. The API produces dates between 1st January 1920 and 1st January 2010. The date will be returned in the format specified. The function accepts strftime() and strptime() format codes. The full list of available date format codes can be found in the Python documentation.
This is how an example request body will look like:

{
 "date": "10-Jul-1950",
 "format": "%d-%b-%Y"
}


You will receive data in the following format:

{
 "date": "04-Jan-1982"
}

Date
Endpoint: https://test.api.randomkey.io/v1/date
Requires: format (string), date (string)
Returns: date (string)
Unique: No
A POST method for retrieving a date. The API produces dates between 1st January 1700 and 1st January 3000. The date will be returned in the format specified. The function accepts strftime() and strptime() format codes. The full list of available date format codes can be found in the Python documentation.
This is how an example request body will look like:

{
 "date": "10/07/1950",
 "format": "%d/%m/%Y"
}


You will receive data in the following format:

{
 "date": "12/03/2982"
}