01 — Authenticate

Get your API key

02 — Try it

Live demo

Enter your email above to start

JSON response will appear here

03 — Reference

Endpoints

GET /v1/profiles List random profiles

GET /v1/profiles/:uuid Get a single profile

POST /v1/keys Request an API key

GET /openapi.json OpenAPI 3.1 spec

GET /health Health check

Query parameters

count /v1/profiles Number of profiles to return (1–100, default 10)

photo_size /v1/profiles Photo size in px (64, 128, 256, 512, 1024 — default 1024)

fields /v1/profiles Comma-separated field groups: name, email, phone, identity, bio, social, physical, job, address, financial, network, documents, interests, education, photo

Usage

terminal

# List 5 profiles
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/v1/profiles?count=5"

# Get a specific profile
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/v1/profiles/PROFILE_UUID"

04 — AI Agents

MCP Server

Use Random Profiles directly from Claude, Cursor, or any MCP-compatible AI agent. Install via npm.

.mcp.json

{
  "mcpServers": {
    "random-profiles": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "random-profiles-mcp"],
      "env": { "RANDOM_PROFILES_API_KEY": "rp_your_key" }
    }
  }
}

05 — Command Line

CLI

Generate profiles from your terminal. Pipe to files, seed databases, or feed into scripts. Install via npm.

terminal

# Get 5 profiles as a table
npx -y random-profiles --count 5 --format table

# Export 50 US profiles to CSV
npx -y random-profiles --count 50 --country US --format csv > profiles.csv

# Filter by gender and age
npx -y random-profiles --gender female --min-age 25 --max-age 35

Response format

{
  "uuid": "a1b2c3d4-...",
  "name": { "prefix": "Ms.", "first": "Jane", "middle": "Marie", "last": "Doe" },
  "email": "jane.doe@example.com",
  "secondary_email": "jane.doe@company.com",
  "phone": "+1-555-123-4567",
  "identity": { "gender": "female", "date_of_birth": "1990-03-15", "nationality": "US", "language": "English", ... },
  "bio": { "username": "jane_doe42", "bio": "Passionate about design.", "website": "https://jane_doe42.dev" },
  "social": { "twitter": "@jane_doe42", "github": "jane_doe42", "instagram": "@jane_doe42", ... },
  "physical": { "height": 168, "weight": 62, "blood_type": "A+", ... },
  "job": { "title": "Software Engineer", "company": "Acme Corp", "industry": "Technology", "company_size": "201-500", ... },
  "address": { "street": "123 Main St", "line_2": "Apt 4B", "city": "Austin", ... },
  "financial": { "credit_card": {...}, "iban": "DE89...", ... },
  "network": { "ip_address": "192.168.1.42", "user_agent": "Mozilla/5.0 ...", "mac_address": "a1:b2:c3:..." },
  "documents": { "ssn_last4": "4821", "passport_number": "912345678", "drivers_license": "D123456789012" },
  "interests": ["hiking", "photography", "cooking"],
  "education": { "degree": "BSc Computer Science", "university": "MIT" },
  "photo": "/images/4f0b7747-....jpg"
}