# Random Profiles API

> Generate fake but realistic user profiles for seed data, test fixtures, and prototypes.

Random Profiles API is a REST API that returns randomized fake user profiles with 100+ fields including names, emails, phone numbers, jobs, addresses, photos, network data, documents, vehicles, and more. Profiles span 9 countries (US, GB, DE, FR, AU, BR, JP, IN, NG) across 6 continents with locale-accurate data.

## API Base URL

https://random-profiles.com

## Authentication

All profile and image endpoints require an `X-API-Key` header. Image endpoints also accept `?key=` as a query parameter (useful for `<img>` tags). Get a free key by POSTing your email to `/v1/keys`.

## Endpoints

- POST /v1/keys — Create an API key (body: {"email": "you@example.com"})
- GET /v1/profiles — List random profiles (auth required)
- GET /v1/profiles/{uuid} — Get a single profile by UUID (auth required)
- GET /v1/images/random — Get a random profile photo as JPEG (auth required)
- GET /v1/images/{uuid} — Get a specific profile photo as JPEG (auth required)
- GET /v1/companies — List random fake company profiles (auth required)
- GET /v1/companies/{uuid} — Get a specific company profile (auth required)
- GET /v1/billing/usage — Check your usage, tier, and daily limits (auth required)
- POST /v1/keys — Create or resend an API key to the given email (email-delivery; response does NOT contain the key)
- POST /v1/keys/instant — Claim an API key non-interactively; returns `{ key, status, email }` in the response body and still emails a receipt. Use this from CLIs, MCP servers, CI — anything that can't read an inbox. Disposable domains rejected; rate limited per IP.
- POST /v1/waitlist — Capture an email address with an optional tier interest (`pro`, `unlimited`, `any`) for notification when paid tiers launch. Idempotent by email; re-posts update the interest.
- GET /v1/waitlist/count — Public count of waitlist signups (for social-proof badges).
- POST /v1/auth/login — Send magic link login email
- GET /v1/auth/me — Get account data (requires session cookie)
- POST /v1/auth/logout — Clear session
- DELETE /v1/auth/account — Delete account and all associated data (GDPR Art. 17, requires session cookie)
- GET /openapi.json — Full OpenAPI 3.1 specification
- GET /health — Health check

## Query Parameters for /v1/profiles

- count (1-100, default 10) — Number of profiles to return
- gender (male|female|non-binary) — Filter by gender
- country (US,GB,DE,FR,AU,BR,JP,IN,NG) — Comma-separated country filter (include)
- exclude_country — Comma-separated country filter (exclude)
- min_age / max_age — Age range filter
- photo_size (64|128|256|512|1024, default 1024) — Photo size in pixels
- fields — Return only specific field groups (comma-separated, see below)
- seed (integer) — Deterministic results, same seed = same profiles
- format (json|csv, default json) — Response format. CSV flattens nested fields with dot notation
- photo_format (jpg|webp, default jpg) — Image format for profile.photo URL. WebP is ~30% smaller.

## Field Groups (for ?fields= parameter)

name, email, phone, identity, bio, social, physical, job, address, financial, network, documents, vehicle, contact, digital, interests, education, photo, relationships, meta

The `relationships` group returns `company_uuid` (lookup via /v1/companies/:uuid) and `colleague_uuids` (up to 5 other profiles at the same company). ~5% of profiles are unemployed (company_uuid: null).

## Query Parameters for /v1/companies

- count (1-100, default 10) — Number of companies to return
- industry — Filter by industry (Technology, Healthcare, Finance, etc.)
- country (US,GB,DE,FR,AU,BR,JP,IN,NG) — Comma-separated country filter
- size — Comma-separated size brackets (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+)
- seed (integer) — Deterministic results
- format (json|csv, default json) — Response format
- fields — Field groups: name, industry, size, location, contact, social, financial, tech, leadership, legal, operations, product, relationships, meta
  The `relationships` group returns `employee_uuids` — up to 30 profiles assigned to the company; hydrate via /v1/profiles/:uuid.
- logo_size — Logo size returned in meta.logo_url (64|128|256|512|1024, default 1024)
- logo_format (jpg|webp, default jpg) — Image format for meta.logo_url. WebP is ~30% smaller.

## Query Parameters for /v1/images/*

- size (64|128|256|512|1024, default 1024) — Photo size in pixels
- format (jpg|webp, default jpg) — Image format. WebP is ~30% smaller than JPG with same perceived quality.
- key — API key (alternative to X-API-Key header, for use in img tags)

## Response Example

```json
{
  "uuid": "a1b2c3d4-...",
  "name": {"prefix": "Ms.", "first": "Elena", "middle": "Sofia", "last": "Vasquez"},
  "gender": "female",
  "email": "elena.vasquez@outlook.com",
  "secondary_email": "elena.vasquez@company.com",
  "phone": "+1-415-555-0142",
  "date_of_birth": "1992-07-23",
  "username": "elena.vasquez",
  "bio": "UX designer and coffee enthusiast.",
  "nationality": "US",
  "language": "English",
  "website": "https://elena.vasquez.dev",
  "social": {"twitter": "@elena.vasquez", "linkedin": "elena.vasquez", "github": "elena-vasquez", "instagram": "@elena_vasquez", "facebook": "elena.vasquez"},
  "physical": {"height": 165, "weight": 58, "blood_type": "A+", "eye_color": "brown", "hair_color": "black"},
  "job": {"title": "Senior UX Designer", "company": "Figma", "department": "Design", "industry": "Technology", "company_size": "201-500", "salary": 142000, "currency": "USD", "start_date": "2021-03-01"},
  "address": {"street": "742 Valencia St", "line_2": null, "city": "San Francisco", "state": "CA", "zip": "94110", "country": "US", "latitude": 37.76, "longitude": -122.42, "timezone": "America/Los_Angeles"},
  "financial": {"credit_card": {"number": "4532-XXXX-XXXX-8901", "type": "Visa"}, "iban": "...", "currency": "USD"},
  "interests": ["typography", "hiking", "photography"],
  "education": {"degree": "BFA Design", "university": "Rhode Island School of Design"},
  "relationship_status": "in a relationship",
  "network": {"ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0...", "mac_address": "00:1B:44:11:3A:B7"},
  "documents": {"ssn_last4": "1234", "passport_number": "123456789", "drivers_license": "A123456789012"},
  "vehicle": {"make": "Tesla", "model": "Model 3", "year": 2023, "license_plate": "ABC-1234"},
  "contact": {"phone_country_code": "+1", "emergency_contact": {"name": "John Doe", "phone": "+1-555-987-6543", "relationship": "spouse"}},
  "digital": {"password_hash": "$2b$10$...", "api_token": "tok_...", "ssh_public_key": "ssh-ed25519 AAAA..."},
  "photo": "https://random-profiles.com/images/4f0b7747-....jpg"
}
```

## Company Response Example

```json
{
  "uuid": "7d3063d3-b62b-41ef-8e60-f5b50dac8ee0",
  "name": "Acme Cloud",
  "legal_name": "Acme Cloud Inc.",
  "legal_form": "Inc.",
  "slug": "acmecloud",
  "domain": "acmecloud.io",
  "description": "Reverse-engineered cloud orchestration platform",
  "tagline": "scale workloads effortlessly",
  "industry": "Technology",
  "sub_industry": "SaaS",
  "type": "private",
  "size": "201-500",
  "tags": ["SaaS", "API-first", "Cloud-native"],
  "location": {"city": "Austin", "state": "TX", "country": "US", "country_name": "United States", "latitude": 30.27, "longitude": -97.74, "timezone": "America/Chicago", "locations": [{"city": "Austin", "country": "US"}, {"city": "Berlin", "country": "DE"}]},
  "contact": {"phone": "+1-512-555-0142", "email": "info@acmecloud.com", "support_email": "support@acmecloud.com", "sales_email": "sales@acmecloud.com", "website": "https://acmecloud.com", "languages": ["English", "Spanish"]},
  "social": {"twitter": "@acmecloud", "linkedin": "acmecloud", "github": "acmecloud", "instagram": "acmecloud", "youtube": "@acmecloud", "crunchbase": "https://www.crunchbase.com/organization/acmecloud"},
  "financial": {"revenue_range": "$10M-$50M", "revenue_usd": 28500000, "funding_total": 45000000, "valuation": 320000000, "ebitda": 5700000, "profit_margin": 0.2, "currency": "USD", "last_round": "Series B", "investors": ["Accel", "Sequoia Capital"], "funding_rounds": [{"round": "Seed", "amount": 3000000, "date": "2019-04-12", "lead_investor": "Accel"}, {"round": "Series A", "amount": 12000000, "date": "2020-10-03", "lead_investor": "Sequoia Capital"}]},
  "legal": {"tax_id": "47-3956214", "duns_number": "12-345-6789", "registration_number": "DE-1234567", "lei": "549300LFAYUXYZ4Q8F92"},
  "leadership": {"ceo_name": "Marcus Chen", "ceo_email": "ceo@acmecloud.com", "cfo_name": "Elena Garcia", "cto_name": "Priya Rao", "founder_names": ["Marcus Chen", "Jake Park"]},
  "product": {"products": ["Cloud Platform", "Cloud API", "Cloud Studio"], "services": ["Implementation", "Training"], "target_market": "B2B", "customer_count": 8400, "nps_score": 62, "competitors": ["Stripe", "Render"]},
  "tech": {"tech_stack": ["React", "Node.js", "PostgreSQL", "AWS", "Datadog"], "frontend": ["React", "Next.js"], "backend": ["Node.js", "Go"], "database": ["PostgreSQL", "Redis"], "cloud": ["AWS"], "security_certifications": ["SOC 2 Type II", "ISO 27001"], "api_docs_url": "https://docs.acmecloud.com", "status_page_url": "https://status.acmecloud.com"},
  "operations": {"status": "active", "is_active": true, "subsidiaries": [], "remote_policy": "remote-first"},
  "meta": {"logo_url": "https://random-profiles.com/logos/abc-123.jpg", "avatar_url": "https://random-profiles.com/avatars/AC.svg", "cover_color": "#3a86ff", "created_at": "2023-05-12T09:14:22Z", "updated_at": "2026-03-14T11:02:17Z"}
}
```

## Pricing

- Free: 100 profiles/day + 500 images/day
- Pro ($5/mo): 10,000 profiles/day + 50,000 images/day
- Unlimited ($15/mo): No limit

Limits are counted per unit: requesting `?count=5` profiles consumes 5 units, each image request consumes 1 unit. A request that would exceed the limit is rejected entirely.

## MCP Server

Available as an npm package for AI agents: `npx -y random-profiles-mcp`
Requires `RANDOM_PROFILES_API_KEY` env var. Tools: get_profiles, get_profile, get_companies, get_company, get_random_image, get_image, get_usage.

## CLI

Available as an npm package: `npx -y random-profiles --count 5`
Requires `RANDOM_PROFILES_API_KEY` env var. Supports json, csv, and table output formats.

## TypeScript types

Available as an npm package: `npm install -D random-profiles-types`
Zero-runtime .d.ts declarations mirroring every /v1/* response shape (Profile, Company, ProfilesResponse, CompaniesResponse, UsageResponse, plus every nested field-group type and enumeration). Use with any HTTP client.

## Comparison vs other tools

Honest 2026 comparison page at https://random-profiles.com/compare — Random Profiles vs Faker, Mockaroo, RandomUser.me, and JSONPlaceholder, with a feature matrix and "when to pick which" guidance.

Random Profiles is differentiated by: (a) 1,000 pre-seeded profiles with stable UUIDs and 100+ fields each, (b) 1,000 companies with AI-generated logos, (c) cross-resource relationships (profile→company_uuid, profile→colleague_uuids, company→employee_uuids), and (d) a native MCP server for zero-config AI agent integration. Faker is the right pick for in-process JS/TS test data; Mockaroo for one-shot SQL/CSV exports; RandomUser.me for friction-free user-only demos; JSONPlaceholder for tutorials needing predictable IDs.

## Example recipes (copy-paste)

Drop-in scripts published at github.com/gusdeboer/random-profiles-mcp/tree/main/examples:

- `seed-prisma.ts` — drop 1,000 users + 1,000 companies into a Prisma + Postgres DB with foreign keys preserved (idempotent upsert by UUID)
- `seed-supabase.ts` — same idea via @supabase/supabase-js, batched upserts of 100, includes the SQL schema
- `playwright-fixture.ts` — Playwright test fixture that hands each test a deterministic fake user + company; hash-of-test-title becomes the seed so failures replay identically
- `mcp-claude-demo.md` — wire random-profiles-mcp into Claude Desktop / Claude Code
- `mcp-cursor-demo.md` — same, for Cursor's MCP integration

## Use Cases

- Seeding databases for development and testing
- Populating UI prototypes with realistic data
- Generating test fixtures for automated tests
- Creating demo environments with fake user data
- Filling design mockups with representative content