Random Data Generator
REST API


Random Data Generator REST API produces fictional - yet realistic - personal data on demand. Returned data is always random within its class. The API supports a variety of services: locations, names, dates, numbers, social security numbers, credit card numbers. The API can be used as a personal data generator in application development. Please consult the Roadmap page for planned release dates of new services.

Example POST request to the Random Data API's Location endpoint:

{
 "headers": {
  "auth": "51349d7defd9351ac",
  "Content-Type": "application/json"
 },
 "body": {
  "region": "us",
  "records": 1
 }
}

(Click Send again for a different response)
Example response:

SUPPORTED API MANAGERS

POSTMAN
Check out our collection on Postman or read our blog post on how to get started!

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 1,000 free requests. To get extra 10,000 requests, fill out our anonymous mini-survey on your intended use of Random Key.

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, Regex, Boolean, Array, Element, First Name, Last Name, Email Address, Phone Number, Location, National Insurance Number, Social Security Number, Numéro de Sécurité Sociale, Internal Russian Passport - Паспорт гражданина Российской Федерации, Credit Card Number, Date, Date & Time, Time

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, in alphabetical order: Australia, Belgium, Canada, Denmark, France, Germany, India, Italy, Netherlands, Poland, Russia, Spain, Sweden, Switzerland, United Kingdom, United States

Australia
Country code: "au"
Supports: Phone Number

Belgium
Country code: "be"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number
The Location service supports the following properties: street, city, postcode

Canada
Country code: "ca"
Supports: Phone Number

Denmark
Country code: "dk"
Supports: Phone Number

France
Country code: "fr"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number, SSN
The Location service supports the following properties: street, city, postcode

Germany
Country code: "de"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number
The Location service supports the following properties: street, city, postcode

India
Country code: "in"
Supports: Phone Number

Italy
Country code: "it"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number
The Location service supports the following properties: street, city, state (abbv), postcode

Netherlands
Country code: "nl"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number
The Location service supports the following properties: street, city, postcode

Poland
Country code: "pl"
Supports: Phone Number

Spain
Country code: "es"
Supports: Phone Number

Sweden
Country code: "se"
Supports: Phone Number

Switzerland
Country code: "ch"
Supports: Phone Number

Russia
Country code: "ru"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number, IRP
The Location service supports the following properties: unit, street, city, state, district (oblast), postcode

UK
Country code: "uk"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number, NIN
The Location service supports the following properties: street, city, postcode

US
Country code: "us"
Supports: Name, First Name, Last Name, Full Name, Location, Phone Number, SSN
The Location service supports the following properties: street, city, state (abbv), postcode (zip)

GET METHODS

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

POST METHODS

Integer
Endpoint: https://random.api.randomkey.io/v1/int
Optional: records (int), nulls (boolean), min (int), max (int)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, min: 1, max: 100
Returns: number (int)
A POST method for producing a random integer within the given range. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:

{
 "min": 28,
 "max": 378
}


You will receive data in the following format:

{
 "number": 223
}

Double
Endpoint: https://random.api.randomkey.io/v1/double
Optional: records (int), nulls (boolean), min (double), max (double)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, min: 1, max: 100
Returns: number (double)
A POST method for producing a random double within the given range. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:

{
 "min": -89.00,
 "max": 12.99
}


You will receive data in the following format:

{
 "number": 5.07
}

Number
Endpoint: https://random.api.randomkey.io/v1/number
Optional: records (int), nulls (boolean), digits (int)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, digits: 4
Returns: number (string)
A POST method for producing a random number of the specified length. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The generated string may include leading zeros.

This is how an example request will look like:

{
 "digits": 9
}


You will receive data in the following format:

{
 "number": "005261992
}

Regex
Endpoint: https://random.api.randomkey.io/v1/regex
Optional: records (int), nulls (boolean), regex (string)
\ Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, regex: "\\w"
Returns: regex (string)
A POST method for producing a random string matching the provided regular expression. Escape the tokens that use a backslash with an additional backslash. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The most common regular expressions are supported, including:
A single character of a, b, or c: [abc]
A character except a, b, or c: [^abc]
A character in the range a-z: [a-z]
A character in the range a-z or A-Z: [a-zA-Z]
A single character: .
A non-whitespace character: \S
A digit: \d
A non-digit: \D
A word character: \w
A non-word character: \W
Exactly 3 of a: a{3}
3 or more of a: a{3,}
Between 3 and 6 of a: a{3,6}
Either a or b: a|b


This is how an example request will look like:

{
 "regex": "\\d\\d [A-Z]{3}"
}


You will receive data in the following format:

{
 "regex": "24 PKH"
}

Boolean
Endpoint: https://random.api.randomkey.io/v1/boolean
Optional: records (int), nulls (boolean)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false
Returns: boolean (boolean)
A POST method for producing a random boolean: True or False. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "boolean": true
}

Array
Endpoint: https://random.api.randomkey.io/v1/array
Optional: records (int), nulls (boolean), array (array), elements (int)
Accepts: nulls: [ true | false ]
Defaults: array: ["Specify your array"], elements: 2, records: 1, nulls: false
Returns: array (array)
A POST method for producing a selection of elements from the provided array. The number of elements to return per array can be specified. Arrays can comprise of various data types. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:

{
 "array": ["oranges","apples","berries"],
 "elements": 2
}


You will receive data in the following format:

{
 "array": [
  "berries",
  "apples"
  ]
}

Element
Endpoint: https://random.api.randomkey.io/v1/element
Optional: array (array)
Accepts: nulls: [ true | false ]
Defaults: array: ["Specify your array"], nulls: false
Returns: ( string | int | double | float | date | boolean | None )
A POST method for producing a random element from the provided array. Arrays can comprise of various data types. The method returns a single value. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:

{
 "array": ["oranges","apples","berries"]
}


You will receive data in the following format:

{
 "element": "oranges"
}

Name
Endpoint: https://random.api.randomkey.io/v1/name
Optional: records (int), nulls (boolean), portion (string), gender (string), region (string)
Accepts: nulls: [ true | false ], portion: [ "first" | "last" | "full" ], gender: [ "f" | "m" | "0" ], region: see Supported Regions
Defaults: records: 1, nulls: false, portion: "first", gender: "0", region: "us"
Returns: name (string)
A POST method for producing a name of the specified name portion (first, last) and gender (male, female, N/A). The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. 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 will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "name": "Edwin"
}

First Name
Endpoint: https://random.api.randomkey.io/v1/name/first
Optional: records (int), nulls (boolean), gender (string), region (string)
Accepts: nulls: [ true | false ], gender: [ "f" | "m" | "0" ], region: see Supported Regions
Defaults: records: 1, nulls: false, gender: "0", region: "us"
Returns: name (string)
A POST method for producing a first name of the specified gender. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. 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 will look like:

{
 "region": "fr",
 "gender": "f"
}


You will receive data in the following format:

{
 "name": "Jacqueline"
}

Last Name
Endpoint: https://random.api.randomkey.io/v1/name/last
Optional: records (int), nulls (boolean), gender (string), region (string)
Accepts: nulls: [ true | false ], gender: [ "f" | "m" | "0" ], region: see Supported Regions
Defaults: records: 1, nulls: false, gender: "0", region: "us"
Returns: name (string)
A POST method for producing a last name. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. 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. Note that specifying gender for the last name is only supported for countries that make that distinction (e.g. Russia), otherwise it's ignored.

This is how an example request will look like:

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


You will receive data in the following format:

{
 "name": "O'Brien"
}

Full Name
Endpoint: https://random.api.randomkey.io/v1/name/full
Optional: records (int), nulls (boolean), gender (string), region (string)
Accepts: nulls: [ true | false ], gender: [ "f" | "m" | "0" ], region: see Supported Regions
Defaults: records: 1, nulls: false, gender: "0", region: "us"
Returns: name (string)
A POST method for producing a full name. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. 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. Note that specifying gender for the last name is only supported for countries that make that distinction (e.g. Russia), otherwise it's ignored.

This is how an example request will look like:

{
 "region": "de",
 "gender": "0"
}


You will receive data in the following format:

{
 "name": "Steffen Göhler"
}

Email Address
Endpoint: https://random.api.randomkey.io/v1/email
Optional: records (int), nulls (boolean)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false
Returns: email (string)
A POST method for producing an email address. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. This is how an example request will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "email": "6ab074a7a241@live.com"
}

Phone Number
Endpoint: https://random.api.randomkey.io/v1/phone
Optional: records (int), nulls (boolean), country_prefix (boolean), idd (string), trunk (string), region (string)
Accepts: nulls: [ true | false ], country_prefix: [ true | false ], idd: [ "" | "00" | "01" | "011" | "010" | "0011" | "810" | "+" ], region: see Supported Regions
Defaults: records: 1, nulls: false, country_prefix: false, idd: "", , trunk: "", region: "us"
Returns: email (string)
A POST method for producing a mobile phone number. The phone number can include a trunk prefix, an IDD code, and/or a country code prefix. By default, only the phone number is returned. 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. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time.

This is how an example request will look like:


 "region": "nl",
 "country_prefix": true,
 "idd": "+"
}


You will receive data in the following format:

{
 "number": "+31647164799"
}

Location
Endpoint: https://random.api.randomkey.io/v1/location
Optional: records (int), nulls (boolean), region (string), and regional properties
Accepts: nulls: [ true | false ]. For region and regional properties: see Supported Regions
Defaults: records: 1, nulls: false, region: "us"
Returns: location ( array | string )
A POST method for producing a full address or a combination of address elements as specified in the request. By default, a complete address is returned. The address is always a real geographical location. The returned array will be different for each region: e.g. for the US, it will comprise of a street (inc. street name and number), city, state (abbreviated name), and a zip code; for Russia, it will produce a unit number, street name, city, state, and district. Any of the properties can be turned off in the request by setting it to False.

The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. 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 and regional properties.

This is how an example request will look like:

{
 "region": "us",
 "state": false
}


You will receive data in the following format:

{
 "location": [
  "4 Acapulco",
  "Vernon",
  "07462"
 ]
}

National Insurance Number
Endpoint: https://random.api.randomkey.io/v1/id/nin
Optional: records (int), nulls (boolean)/a>
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false
Returns: id (string)
A POST method for producing random British National Insurance Numbers. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The NIN numbers have been generated by following the HMRC specification for a valid NIN format.

This is how an example request will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "id": "JA908605C"
}

Social Security Number
Endpoint: https://random.api.randomkey.io/v1/id/ssn
Optional: records (int), nulls (boolean)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false
Returns: id (string)
A POST method for producing random Social Security Numbers. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The SSN numbers have been generated by following the SSA specification for a valid SSN format.

This is how an example request will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "id": "541856759"
}

Numéro de Sécurité Sociale
Endpoint: https://random.api.randomkey.io/v1/id/nss
Optional: records (int), nulls (boolean), gender (string), portion (string)
Accepts: nulls: [ true | false ], gender: [ "0" | "f" | "m" ], portion: [ "full" | "number" ]
Defaults: records: 1, nulls: false, gender: "0", portion: "full"
Returns: id (array)
A POST method for producing random French social security number, i.e. numéro de sécurité sociale. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The method returns a Date of Birth based on the information derived from the NSS, unless specified otherwise. The NSS numbers have been generated by following the INSEE specification for a valid NSS format. You can specify the gender in the request.

This is how an example request will look like:

{
 "gender": "f",
 "portion": "full",
 "records": 1
}


You will receive data in the following format:

{
 "id": [
  "287093138175228",
  "10/09/87"
 ]
}

Internal Russian Passport
Endpoint: https://random.api.randomkey.io/v1/id/irp
Optional: records (int), nulls (boolean)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false
Returns: id (string)
A POST method for producing random 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:

{
 "records": 1
}


You will receive data in the following format:

{
 "id": "2460274745"
}

Credit Card Number
Endpoint: https://random.api.randomkey.io/v1/ccn
Optional: records (int), nulls (boolean), portion (string), valid (boolean), luhn (boolean)
Accepts: nulls: [ true | false ], portion: [ "full" | "number" ], valid: [ true | false ], luhn: [ true | false ]
Defaults: records: 1, nulls: false, portion: "number", valid: true, luhn: true
Returns: ccn ( string | array )
A POST method for producing random Payment Card Numbers. The card numbers will pass or fail the Luhn check as specified. The cards will carry an invalid date if the valid flag is set to False. The generated response returns card numbers by default but can be configured to include the expiry month and the security code. 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. American Express have exactly 15 digits. The method generates up to 10,000 records per request.

This is how an example request will look like:

{
 "records": 1
}


You will receive data in the following format:

{
 "ccn": "3905960920701157418"
}

Date
Endpoint: https://random.api.randomkey.io/v1/date
Optional: records (int), nulls (boolean), min (string), max (string), format (string)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, min: "01-Jan-1990", max: "31-Dec-2020", format: "%d-%b-%Y"
Returns: date (string)
A POST method for producing a random date within the given range and in the format specified. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The format has to match that of the provided range. 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 will look like:

{
 "min": "10-Jul-2010",
 "max": "10-Aug-2012",
 "format": "%d-%b-%Y",
 "records": 1
}


You will receive data in the following format:

{
 "date": "04-May-2011"
}

Datetime
Endpoint: https://random.api.randomkey.io/v1/datetime
Optional: records (int), nulls (boolean), min (string), max (string), format (string)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, min: "01-Jan-1990 00:00", max: "31-Dec-2020 23:59", format: "%d-%b-%Y %H:%M"
Returns: datetime (string)
A POST method for producing a random date and time within the given range and in the format specified. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The format has to match that of the provided range. The function accepts strftime() and strptime() format codes. The format has to match that of the provided range. The full list of available date format codes can be found in the Python documentation.

This is how an example request will look like:

{
 "min": "10/Jul/2010 10:00",
 "max": "10/Aug/2012 12:00",
 "format": "%d/%b/%Y %I:%M",
 "records": 1
}


You will receive data in the following format:

{
 "datetime": "12/Aug/2010 04:30"
}

Time
Endpoint: https://random.api.randomkey.io/v1/time
Optional: records (int), nulls (boolean), min (string), max (string), format (string)
Accepts: nulls: [ true | false ]
Defaults: records: 1, nulls: false, min: "01-Jan-1990 00:00", max: "31-Dec-2020 23:59", format: "%d-%b-%Y %H:%M"
Returns: time (string)
A POST method for producing random time within the given range and in the format specified. The method generates up to 10,000 records per request. If the null flag is set to true, a null value will be produced 10% of time. The format has to match that of the provided range. The function accepts strftime() and strptime() format codes. The format has to match that of the provided range. The full list of available date format codes can be found in the Python documentation.

This is how an example request will look like:

{
 "min": "10:00",
 "max": "12:00",
 "format": "%I:%M"
}


You will receive data in the following format:

{
 "time": "11:21"
}