openapi: 3.0.3
info:
title: Random User Generator Users API
description: 'Free, open-source REST API that generates random user data for application testing,
prototyping, and demo content. Returns rich, realistic synthetic user records
(name, location, login, contact, picture, identification) across multiple
nationalities, with deterministic reproducibility via seeds.
Powered by the open-source project https://github.com/RandomAPI/Randomuser.me-Node
and funded by community donations (no API key, no rate limit gate).
'
version: '1.4'
contact:
name: RandomAPI
url: https://randomuser.me
license:
name: MIT
url: https://github.com/RandomAPI/Randomuser.me-Node/blob/master/LICENSE
x-generated-from: documentation
x-source-url: https://randomuser.me/documentation
x-last-validated: '2026-05-29'
servers:
- url: https://randomuser.me/api
description: Production API (auto-selects latest version)
- url: https://randomuser.me/api/1.4
description: Pinned to version 1.4
tags:
- name: Users
description: Generate one or more synthetic user records.
paths:
/:
get:
operationId: generateUsers
summary: Generate Random Users
description: 'Generate one or more random user records. Supports controlling result count,
gender, nationality mix, included/excluded fields, password composition,
format (JSON/CSV/YAML/XML/PrettyJSON), seeded reproducibility, and pagination.
'
tags:
- Users
parameters:
- name: results
in: query
description: Number of user records to generate. Maximum 5000 per request.
required: false
schema:
type: integer
minimum: 1
maximum: 5000
default: 1
example: 10
- name: gender
in: query
description: Restrict to a single gender. Omit or use any other value to return both.
required: false
schema:
type: string
enum:
- male
- female
example: female
- name: nat
in: query
description: 'Comma-separated list of two-letter nationality codes. Supported (v1.4):
AU, BR, CA, CH, DE, DK, ES, FI, FR, GB, IE, IN, IR, MX, NL, NO, NZ,
RS, TR, UA, US. Omit for a mix of all nationalities.
'
required: false
schema:
type: string
example: us,gb,fr
- name: inc
in: query
description: 'Comma-separated list of top-level fields to include. Allowed values:
gender, name, location, email, login, registered, dob, phone, cell,
id, picture, nat. Mutually exclusive with `exc`.
'
required: false
schema:
type: string
example: name,email,nat
- name: exc
in: query
description: 'Comma-separated list of top-level fields to exclude. Allowed values
same as `inc`. Mutually exclusive with `inc`.
'
required: false
schema:
type: string
example: login
- name: seed
in: query
description: 'Deterministic seed. The same seed (with the same page, results, and
version) always returns the same users.
'
required: false
schema:
type: string
example: foobar
- name: page
in: query
description: 'Page number (1-based) for paginated seeded results. Use with `seed`
and a fixed `results` value to walk a stable dataset.
'
required: false
schema:
type: integer
minimum: 1
default: 1
example: 3
- name: format
in: query
description: 'Response serialization format. Defaults to JSON.
'
required: false
schema:
type: string
enum:
- json
- pretty
- csv
- yaml
- xml
default: json
example: csv
- name: password
in: query
description: 'Password composition rules: `CHARSETS,MIN-MAX` or `CHARSETS,MAX`.
Charsets: special, upper, lower, number (comma-separated, in any order).
Default: ~10k top-used passwords; otherwise 8-64 characters.
'
required: false
schema:
type: string
example: upper,lower,number,8-16
- name: dl
in: query
description: 'If present, returns the response as a file download with the
appropriate extension for the requested `format`.
'
required: false
schema:
type: boolean
- name: noinfo
in: query
description: 'If present, omits the `info` envelope (seed, results, page, version)
from the response.
'
required: false
schema:
type: boolean
- name: callback
in: query
description: 'JSONP callback function name. Only honored for JSON formats.
'
required: false
schema:
type: string
example: randomuserdata
responses:
'200':
description: A randomly generated user payload.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
examples:
singleUser:
summary: Default request (one user)
value:
results:
- gender: female
name:
title: Miss
first: Jennie
last: Nichols
email: jennie.nichols@example.com
nat: US
info:
seed: 56d27f4a53bd5441
results: 1
page: 1
version: '1.4'
text/csv:
schema:
type: string
application/xml:
schema:
type: string
application/x-yaml:
schema:
type: string
'500':
description: Server error from the generator.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/{version}/:
get:
operationId: generateUsersVersioned
summary: Generate Random Users (Pinned Version)
description: 'Same as `generateUsers` but pinned to a specific API version so future
releases cannot break the response shape. Supported versions: 1.0, 1.1,
1.2, 1.3, 1.4.
'
tags:
- Users
parameters:
- name: version
in: path
required: true
description: API version to pin (e.g. `1.4`).
schema:
type: string
enum:
- '1.0'
- '1.1'
- '1.2'
- '1.3'
- '1.4'
example: '1.4'
- $ref: '#/paths/~1/get/parameters/0'
- $ref: '#/paths/~1/get/parameters/1'
- $ref: '#/paths/~1/get/parameters/2'
- $ref: '#/paths/~1/get/parameters/3'
- $ref: '#/paths/~1/get/parameters/4'
- $ref: '#/paths/~1/get/parameters/5'
- $ref: '#/paths/~1/get/parameters/6'
- $ref: '#/paths/~1/get/parameters/7'
- $ref: '#/paths/~1/get/parameters/8'
- $ref: '#/paths/~1/get/parameters/9'
- $ref: '#/paths/~1/get/parameters/10'
- $ref: '#/paths/~1/get/parameters/11'
responses:
'200':
description: A randomly generated user payload.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
User:
type: object
description: A single synthetic user record.
properties:
gender:
type: string
enum:
- male
- female
example: female
name:
$ref: '#/components/schemas/Name'
location:
$ref: '#/components/schemas/Location'
email:
type: string
format: email
example: jennie.nichols@example.com
login:
$ref: '#/components/schemas/Login'
dob:
$ref: '#/components/schemas/DateWithAge'
registered:
$ref: '#/components/schemas/DateWithAge'
phone:
type: string
example: (272) 790-0888
cell:
type: string
example: (489) 330-2385
id:
$ref: '#/components/schemas/Id'
picture:
$ref: '#/components/schemas/Picture'
nat:
type: string
description: ISO 3166-1 alpha-2 country code for the user's nationality.
example: US
Name:
type: object
properties:
title:
type: string
example: Miss
first:
type: string
example: Jennie
last:
type: string
example: Nichols
Picture:
type: object
properties:
large:
type: string
format: uri
example: https://randomuser.me/api/portraits/men/75.jpg
medium:
type: string
format: uri
example: https://randomuser.me/api/portraits/med/men/75.jpg
thumbnail:
type: string
format: uri
example: https://randomuser.me/api/portraits/thumb/men/75.jpg
UserResponse:
type: object
description: Standard envelope returned by the generator.
properties:
results:
type: array
items:
$ref: '#/components/schemas/User'
info:
$ref: '#/components/schemas/Info'
required:
- results
- info
Location:
type: object
properties:
street:
type: object
properties:
number:
type: integer
example: 8929
name:
type: string
example: Valwood Pkwy
city:
type: string
example: Billings
state:
type: string
example: Michigan
country:
type: string
example: United States
postcode:
oneOf:
- type: string
- type: integer
example: '63104'
coordinates:
type: object
properties:
latitude:
type: string
example: '-69.8246'
longitude:
type: string
example: '134.8719'
timezone:
type: object
properties:
offset:
type: string
example: '+9:30'
description:
type: string
example: Adelaide, Darwin
Login:
type: object
properties:
uuid:
type: string
format: uuid
example: 7a0eed16-9430-4d68-901f-c0d4c1c3bf00
username:
type: string
example: yellowpeacock117
password:
type: string
example: addison
salt:
type: string
example: sld1yGtd
md5:
type: string
example: ab54ac4c0be9480ae8fa5e9e2a5196a3
sha1:
type: string
example: edcf2ce613cbdea349133c52dc2f3b83168dc51b
sha256:
type: string
example: 48df5229235ada28389b91e60a935e4f9b73eb4bdb855ef9258a1751f10bdc5d
Error:
type: object
properties:
error:
type: string
example: Uh oh, something has gone wrong. Please tweet us @randomapi about the issue. Thank you.
required:
- error
DateWithAge:
type: object
properties:
date:
type: string
format: date-time
example: 1992-03-08 15:13:16.688000+00:00
age:
type: integer
example: 30
Id:
type: object
properties:
name:
type: string
example: SSN
description: Identifier scheme (varies by nationality; may be empty).
value:
type: string
nullable: true
example: 405-88-3636
Info:
type: object
description: Metadata about the generated batch.
properties:
seed:
type: string
example: 56d27f4a53bd5441
results:
type: integer
example: 1
page:
type: integer
example: 1
version:
type: string
example: '1.4'
required:
- seed
- results
- page
- version