Reference

Docs.

What peoplesets generates, what knobs you have, and the exact shape of the parquet you'll read. Live-fetched from the API — if you see it here, it's in the engine.

Get started

Quickstart

1. Get a key

Drop your email at peoplesets.com#get-key. We mint it inline and show it once. Save it.

2. Make a call

Every endpoint takes Authorization: Bearer $K. The most common one is POST /generate-company.

POST /generate-company

curl -X POST https://peoplesets-api-production.up.railway.app/generate-company \
  -H "Authorization: Bearer $PEOPLESETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry_pack": "tech_startup",
    "size": 500,
    "seed": 42
  }'

3. Poll until done

Jobs run async. Status goes pending → running → done. Default sims finish in 1–3 seconds; 10k-person sims take 20–40s.

curl -s -H "Authorization: Bearer $PEOPLESETS_API_KEY" \
  https://peoplesets-api-production.up.railway.app/jobs/$JOB_ID

4. Download the zip

curl -L -H "Authorization: Bearer $PEOPLESETS_API_KEY" \
  https://peoplesets-api-production.up.railway.app/jobs/$JOB_ID/artifacts.zip \
  -o peoplesets-$JOB_ID.zip
unzip -l peoplesets-$JOB_ID.zip
# employees.parquet  events.parquet  comp_events.parquet  recruiting.parquet
# summary.md         data_dictionary.md

Catalog

Industry packs

Curated configs that shape the dataset into a recognizable narrative. Pass the name as industry_pack on /generate-company.

Healthcare system

industry_pack: healthcare_system

3,000-employee regional hospital network. Heavy clinical operations, significant administrative tail, regulated comp bands, and low attrition characteristic of credentialed healthcare workforces (<8% annualized). US-only. Slower promotion cadence than tech; equity not material.

Retail chain

industry_pack: retail_chain

Regional retail chain ~5,000 employees split between HQ corporate and store-frontline staff. Frontline (L1/L2 in CustomerSuccess, Sales, Operations) dominates headcount and exhibits the high turnover real retail companies see (30%+ annualized at the frontline). US + Canada footprint with hourly comp dominant at the junior levels.

Tech startup

industry_pack: tech_startup

Series-B / early Series-C software company. ~200 employees, heavily engineering-weighted (>40% of headcount), US-headquartered with a small international presence, aggressive promotion cadence, equity-rich comp at L4+. Standard 3-year simulation produces a clear hyper-growth signature followed by typical scaleup attrition.

Catalog

Scenarios

Narrative events layered onto a base sim. Use special_events: ["name"] on /generate-company, or call POST /apply-scenario with a single scenario for the shortcut path.

Reduction in force

scenario: rif

A mid-sim involuntary headcount reduction concentrated in the lowest-performing 2–4% of the company. Produces clear `layoff` events in the events table and a step-down in active headcount.

Param	Type	Default	Description
`pct`	`number`	`0.03`	Fraction of headcount cut (0.01–0.10).
`quarter`	`string`	`Q3`	Quarter to land the cut (Q1/Q2/Q3/Q4).

Hyper-growth ramp

scenario: hyper_growth

Doubles the base hiring rate and accelerates org expansion. Use this for a 'we just raised a Series C' narrative — the events frame shows visibly more hires in the second half of the sim.

Param	Type	Default	Description
`multiplier`	`number`	`2`	Hiring-rate multiplier (default 2.0).

Merger or acquisition

scenario: m_and_a

Mid-sim acquired team appears as a burst of hires from a single department, plus a follow-up wave of integration-driven attrition. Use for post-acquisition demos.

Param	Type	Default	Description
`acquired_size`	`integer`	`50`	Headcount of the acquired team.

Distressed company

scenario: distressed

Elevates voluntary attrition across the board (recession-grade exit pressure) and suppresses promotion velocity. Use for 'retention crisis' demos.

Leadership shake-up

scenario: leadership_shake_up

Mid-sim involuntary terminations concentrated at L6+ (VP and above), followed by a backfill wave from external hiring. Use for 'new CEO swept the bench' narratives.

Schema

Data dictionary

Four parquet files per run. Schema is additive — new columns appear, existing columns never change shape, so downstream code keeps working.

employees.parquet

Employee roster with demographics, compensation, performance, and org hierarchy.

Column	Description
`employee_id`	Unique identifier for each employee (e.g., EMP0000001)
`full_name`	Employee full name (synthetic)
`grade`	Job grade/level (L1-L8)
`department`	Department name
`is_manager`	Whether the employee is a people manager
`gender`	Gender identity
`ethnicity`	Ethnicity/race category
`age_range`	Age bracket (e.g., 25-34)
`location`	Office location
`hire_date`	Date the employee was hired
`base_salary`	Current base salary in USD
`current_performance`	Most recent performance rating (1.0-5.0)
`current_engagement`	Most recent engagement score (1.0-5.0)
`job_title`	Job title based on department and grade
`status`	Employment status: active or terminated
`termination_date`	Date of termination (null if active)
`termination_type`	Voluntary or involuntary (null if active)
`termination_reason`	Reason for termination (null if active)
`manager_id`	Employee ID of direct manager (foreign key -> employee_id)
`promotion_count`	Number of promotions received
`last_promotion_date`	Date of most recent promotion
`last_merit_date`	Date of most recent merit increase
`emp_type`	Employment type (permanent)
`fte`	Full-time equivalent (1.0 = full time)
`country`	ISO3 country of employment (USA, GBR, CAN, IND, DEU, AUS, BRA, IRL)
`city`	City of employment within the employee's country
`currency`	Local-payroll currency for the employee's country (USD, GBP, EUR, INR, ...)
`org_level_1`	Top-level org hierarchy label
`business_unit`	Business-unit rollup of the employee's department (Technology, Go-To-Market, G&A)
`cost_center`	Cost-center code derived from family + country + department (e.g., CC-ENG-USA-42)
`job_family`	Canonical family key from the job architecture (Engineering, Product, Sales, ...)
`job_level`	Integer level 1..8 within the job family
`track`	Career track: IC (individual contributor) or Manager (people-leader)
`job_code`	Stable internal code combining family, level, and track (e.g., ENG-03-I)
`name_locale`	Country code whose name pool generated the employee's full_name
`local_salary`	Base salary expressed in the employee's local currency (base_salary * geo multiplier)
`equity_grant_value`	USD value of outstanding equity grant; populated for L4+ employees, otherwise null
`tenure_days`	Days employed (calculated at simulation end)
`tenure_years`	Years employed (calculated at simulation end)

events.parquet

Chronological log of all workforce events (hires, terminations, promotions, reviews, etc.).

Column	Description
`event_id`	Unique event identifier (e.g., EVT000000001)
`event_type`	Event kind: hire, termination, promotion, perf_review, merit, reorg, layoff, hiring_freeze, leave_start, leave_end
`employee_id`	Employee this event pertains to (foreign key -> employees.employee_id; 'ORG' for company-wide events)
`event_date`	Date the event occurred
`grade`	Employee grade at time of event ('ALL' for company-wide events)
`department`	Employee department at time of event ('ALL' for company-wide events)
`source`	Hiring source (for hire events): growth, ramp, backfill, founding
`salary`	Salary at hire (for hire events)
`type`	Termination type (for termination events): voluntary or involuntary
`reason`	Termination reason (for termination/layoff events)
`old_grade`	Grade before promotion (for promotion events)
`new_grade`	Grade after promotion (for promotion events)
`old_salary`	Salary before change
`new_salary`	Salary after change
`performance`	Performance rating (for review events)
`engagement`	Engagement score (for review events)
`prior_performance`	Performance rating before event
`from_grade`	Grade before promotion
`to_grade`	Grade after promotion
`leave_type`	Category of leave (for leave_start events): parental_or_medical
`reorg_id`	Identifier of the reorg this event belongs to (e.g., REORG-001)
`affected_count`	Number of employees affected by a company-wide event (reorg, layoff)
`layoff_pct`	Fraction of headcount targeted by a layoff event header
`duration_weeks`	Length of a hiring-freeze window in weeks
`end_date`	End date of a hiring-freeze window (ISO format)

comp_events.parquet

Compensation change events with before/after salary data.

Column	Description
`comp_event_id`	Unique compensation event identifier (e.g., CMP000000001)
`employee_id`	Employee this event pertains to (foreign key -> employees.employee_id)
`event_date`	Date the compensation change occurred
`event_type`	Type: merit_increase, promotion_increase, market_adjustment
`old_salary`	Salary before the change
`new_salary`	Salary after the change
`change_amount`	Absolute dollar change (new - old)
`change_pct`	Percentage change as decimal (e.g., 0.04 = 4%)
`grade`	Employee grade at time of comp event
`department`	Employee department at time of comp event

recruiting.parquet

Recruiting funnel data for each hire, from requisition open to close.

Column	Description
`requisition_id`	Unique requisition identifier (e.g., REQ0000001)
`employee_id`	Hired employee ID (foreign key -> employees.employee_id)
`grade`	Grade level of the position
`department`	Department of the position
`open_date`	Date the requisition was opened
`close_date`	Date the requisition was filled
`time_to_fill_days`	Days from open to close
`source`	Recruiting source (job_board, referral, etc.)
`applications`	Total number of applications received
`reviewed`	Number of applications that passed initial review
`phone_screens`	Number of phone screens conducted
`assessments`	Number of assessments completed
`interviews`	Number of interviews conducted
`offers_extended`	Number of offers extended
`outcome`	Outcome of the requisition (hired)

Going deeper

API reference

For the full OpenAPI spec — every endpoint, every field, every response code — see the live Swagger UI. It's the source of truth.

Open API reference →