{"openapi":"3.0.3","info":{"title":"LifeSim API","version":"3.0.0","description":"Generate fictional people whose attributes are weighted by US Census and survey data. Every person is made up. Use a seed to get the same person again.","contact":{"name":"Craig Vander Galien","url":"https://lifesim.io"},"license":{"name":"Proprietary","url":"https://lifesim.io"}},"servers":[{"url":"https://lifesim.io"}],"paths":{"/api/":{"get":{"operationId":"generatePerson","summary":"Generate people (v2-compatible)","description":"The original v2 endpoint, served unchanged by the original generator for existing clients. For repeatable seeds and batches, use /api/v1/people.","parameters":[{"name":"num","in":"query","required":false,"description":"How many people to generate.","schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"example":5},{"name":"seed","in":"query","required":false,"description":"Seed for a repeatable result. The same seed returns the same person. With num > 1, person 0 uses this seed and the rest use derived seeds.","schema":{"type":"integer","minimum":0,"maximum":2147483647},"example":12345}],"responses":{"200":{"description":"The generated people.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/api/v1/people":{"get":{"operationId":"listPeople","summary":"Generate people as JSON or CSV","parameters":[{"name":"num","in":"query","required":false,"description":"How many people to generate.","schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"example":5},{"name":"seed","in":"query","required":false,"description":"Seed for a repeatable result. The same seed returns the same person. With num > 1, person 0 uses this seed and the rest use derived seeds.","schema":{"type":"integer","minimum":0,"maximum":2147483647},"example":12345},{"name":"format","in":"query","required":false,"description":"json (default) or csv. CSV has one row per person with dotted column names.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The generated people.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"A parameter is out of range. The message says which one and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The generator cannot make a person from this seed (upstream engine only). Try another seed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The upstream generator did not answer (upstream engine only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Reference data is not loaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiResponse":{"type":"object","properties":{"time":{"type":"number","description":"Generation time in seconds"},"people":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"}]}},"required":["time","people"]},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_num","invalid_seed","invalid_format","seed_unavailable","upstream_failed","unavailable"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Person":{"type":"object","properties":{"seed":{"type":"integer","minimum":0,"maximum":2147483647,"description":"Seed for this person; pass it back to get the same person"},"name_first":{"type":"string","description":"First name"},"name_last":{"type":"string","description":"Last name"},"age":{"type":"integer","minimum":0,"maximum":110,"description":"Age in years on the generation date"},"birth_day":{"type":"string","format":"date","description":"Date of birth, YYYY-MM-DD"},"physical":{"$ref":"#/components/schemas/Physical"},"location":{"$ref":"#/components/schemas/Location"},"income":{"$ref":"#/components/schemas/Income"},"education":{"$ref":"#/components/schemas/Education"},"employment":{"$ref":"#/components/schemas/Employment"},"children":{"type":"object","properties":{"children":{"type":"boolean","description":"Has children"},"count":{"description":"Number of children, when children is true","type":"integer"}},"required":["children"],"description":"Children"},"housing":{"$ref":"#/components/schemas/Housing"},"pets":{"$ref":"#/components/schemas/Pets"},"veteran":{"$ref":"#/components/schemas/Veteran"},"social_media":{"$ref":"#/components/schemas/SocialMedia"},"vehicles":{"$ref":"#/components/schemas/Vehicles"},"phone":{"$ref":"#/components/schemas/Phone"},"email":{"$ref":"#/components/schemas/Email"},"religion":{"type":"string","description":"Religious affiliation"},"religiousity":{"type":"integer","minimum":0,"maximum":100,"description":"How religious, 0 to 100 (spelling kept from API v2)"},"favorite_color":{"type":"string","description":"Favorite color"},"smoking":{"type":"object","properties":{"smoking":{"type":"boolean","description":"Smokes cigarettes"}},"required":["smoking"],"description":"Smoking"},"swim_ability":{"type":"boolean","description":"Can swim"},"personality":{"$ref":"#/components/schemas/Personality"},"tendencies":{"$ref":"#/components/schemas/Tendencies"},"timeline":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TimelineEvent"},"description":"Life events keyed by name, for example birth or wedding"},"summary":{"type":"string","description":"One-paragraph description"},"married":{"$ref":"#/components/schemas/MaritalStatus"}},"required":["seed","name_first","name_last","age","birth_day","physical","location","income","education","employment","children","housing","pets","veteran","social_media","vehicles","phone","email","religion","religiousity","favorite_color","smoking","swim_ability","personality","tendencies","timeline","summary","married"],"description":"One fictional person"},"Spouse":{"type":"object","properties":{"seed":{"type":"integer","minimum":0,"maximum":2147483647,"description":"Seed for this person; pass it back to get the same person"},"name_first":{"type":"string","description":"First name"},"name_last":{"type":"string","description":"Last name"},"age":{"type":"integer","minimum":0,"maximum":110,"description":"Age in years on the generation date"},"birth_day":{"type":"string","format":"date","description":"Date of birth, YYYY-MM-DD"},"physical":{"$ref":"#/components/schemas/Physical"},"location":{"$ref":"#/components/schemas/Location"},"income":{"$ref":"#/components/schemas/Income"},"education":{"$ref":"#/components/schemas/Education"},"employment":{"$ref":"#/components/schemas/Employment"},"children":{"type":"object","properties":{"children":{"type":"boolean","description":"Has children"},"count":{"description":"Number of children, when children is true","type":"integer"}},"required":["children"],"description":"Children"},"housing":{"$ref":"#/components/schemas/Housing"},"pets":{"$ref":"#/components/schemas/Pets"},"veteran":{"$ref":"#/components/schemas/Veteran"},"social_media":{"$ref":"#/components/schemas/SocialMedia"},"vehicles":{"$ref":"#/components/schemas/Vehicles"},"phone":{"$ref":"#/components/schemas/Phone"},"email":{"$ref":"#/components/schemas/Email"},"religion":{"type":"string","description":"Religious affiliation"},"religiousity":{"type":"integer","minimum":0,"maximum":100,"description":"How religious, 0 to 100 (spelling kept from API v2)"},"favorite_color":{"type":"string","description":"Favorite color"},"smoking":{"type":"object","properties":{"smoking":{"type":"boolean","description":"Smokes cigarettes"}},"required":["smoking"],"description":"Smoking"},"swim_ability":{"type":"boolean","description":"Can swim"},"personality":{"$ref":"#/components/schemas/Personality"},"tendencies":{"$ref":"#/components/schemas/Tendencies"},"timeline":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TimelineEvent"},"description":"Life events keyed by name, for example birth or wedding"},"summary":{"type":"string","description":"One-paragraph description"},"married":{"type":"object","properties":{"married":{"type":"boolean","description":"Currently married"},"wedding_day":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Wedding date"},"date_formatted":{"type":"string","description":"Wedding date as text, for example July 4, 1995"},"age":{"type":"integer","description":"Age at the wedding"}},"required":["date","date_formatted","age"]}},"required":["married"],"description":"Marriage"}},"required":["seed","name_first","name_last","age","birth_day","physical","location","income","education","employment","children","housing","pets","veteran","social_media","vehicles","phone","email","religion","religiousity","favorite_color","smoking","swim_ability","personality","tendencies","timeline","summary","married"],"description":"The spouse, a full person record without a nested spouse"},"Physical":{"type":"object","properties":{"gender":{"type":"string","enum":["Male","Female"],"description":"Sex as recorded on the census form"},"height":{"type":"object","properties":{"cm":{"type":"integer","description":"Height in centimeters"},"imperial":{"type":"object","properties":{"ft":{"type":"integer","description":"Feet part of the height"},"in":{"type":"integer","minimum":0,"maximum":11,"description":"Inches part of the height"}},"required":["ft","in"]}},"required":["cm","imperial"]},"weight":{"type":"object","properties":{"kg":{"type":"integer","description":"Weight in kilograms"},"lbs":{"type":"integer","description":"Weight in pounds"},"bmi":{"type":"integer","description":"Body mass index, rounded"},"bmiDescription":{"type":"string","enum":["Underweight","Healthy Weight","Overweight","Obese"],"description":"CDC BMI category"}},"required":["kg","lbs","bmi","bmiDescription"]},"hair_color":{"type":"string","description":"Hair color"},"eye_color":{"type":"string","description":"Eye color"},"race":{"type":"string","description":"Race or ethnicity, drawn from the place's population mix"},"sexuality":{"type":"string","description":"Sexual orientation"},"handedness":{"type":"string","enum":["Right Handed","Left Handed","Ambidextrous"],"description":"Dominant hand"},"vision":{"type":"object","properties":{"color_vision":{"type":"boolean","description":"True when the person is not color blind"}},"required":["color_vision"]},"lactose_tolerance":{"type":"boolean","description":"Can digest lactose"},"blood_type":{"type":"string","enum":["O+","O-","A+","A-","B+","B-","AB+","AB-"],"description":"ABO and Rh blood type, weighted by race"},"allergies":{"type":"array","items":{"type":"string"},"description":"Food, environmental and drug allergies"},"has_allergies":{"type":"boolean","description":"True when allergies is not empty"},"pronouns":{"type":"object","properties":{"personal":{"type":"string","description":"Subject pronoun, for example she"},"possessive":{"type":"string","description":"Possessive pronoun, for example her"},"objective":{"type":"string","description":"Object pronoun, for example her"}},"required":["personal","possessive","objective"]},"piercing":{"type":"object","properties":{"earlobe":{"type":"boolean","description":"Has pierced earlobes"}},"required":["earlobe"]}},"required":["gender","height","weight","hair_color","eye_color","race","sexuality","handedness","vision","lactose_tolerance","blood_type","allergies","has_allergies","pronouns","piercing"],"description":"Body and health"},"Location":{"type":"object","properties":{"id":{"type":"string","description":"Census-style place id, 1600000US + state FIPS + place code"},"city":{"type":"string","description":"City or town"},"state":{"type":"string","description":"State name"},"state_abbrev":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter state code"},"location":{"type":"string","description":"City and state as one string"},"population":{"type":"string","description":"Place population (a string, as in API v2)"},"density":{"type":"string","enum":["urban","suburban","rural"],"description":"Settlement type"},"location_exact":{"type":"object","properties":{"lat":{"type":"number","description":"Latitude of a point near the place"},"lng":{"type":"number","description":"Longitude of a point near the place"}},"required":["lat","lng"]},"races":{"type":"object","properties":{"white":{"type":"string","description":"Share of the place that is White, percent"},"black":{"type":"string","description":"Share that is Black, percent"},"asian":{"type":"string","description":"Share that is Asian, percent"},"american_indian":{"type":"string","description":"Share that is American Indian or Alaska Native, percent"},"hispanic":{"type":"number","description":"Share that is Hispanic or Latino, percent (a number, as in API v2)"}},"required":["white","black","asian","american_indian","hispanic"]}},"required":["id","city","state","state_abbrev","location","population","density","location_exact","races"],"description":"Where the person lives"},"Income":{"type":"object","properties":{"amount":{"type":"integer","description":"Annual income in US dollars"},"min":{"type":"integer","description":"Lower bound of the income bracket"},"max":{"type":"integer","description":"Upper bound of the income bracket"},"num":{"type":"number","description":"Income percentile, 1 to 99"}},"required":["amount","min","max","num"],"description":"Annual income"},"Education":{"type":"object","properties":{"education_highest":{"type":"string","enum":["No High School","Some High School","High School Graduate","Some College","Associate's degree","Bachelor's degree","Master's degree","Doctorate"],"description":"Highest level finished"}},"required":["education_highest"],"description":"Schooling"},"Employment":{"type":"object","properties":{"status":{"type":"string","enum":["Employed","Unemployed","Retired","Student"],"description":"Work status"},"company":{"type":"object","properties":{"size":{"type":"string","enum":["Small","Medium","Large"],"description":"Employer size"}},"required":["size"]},"schedule":{"type":"object","properties":{"start":{"type":"string","description":"Shift start, 24-hour H:MM"},"end":{"type":"string","description":"Shift end, 24-hour H:MM"},"days":{"type":"object","properties":{"text":{"type":"string","description":"Working days as text, for example Monday-Friday"},"day_nums":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"Working days, 0 = Sunday"}},"required":["text","day_nums"]}},"required":["start","end","days"]},"commute":{"type":"object","properties":{"time":{"type":"integer","description":"One-way commute in minutes"},"type":{"type":"string","description":"Mode: car, bus, train, bike, walk or remote"},"description":{"type":"string","description":"One sentence about the commute"},"text":{"type":"string","description":"Mode as a phrase, for example by car"}},"required":["time","type","description","text"]}},"required":["status","company","schedule","commute"],"description":"Work"},"MaritalStatus":{"type":"object","properties":{"married":{"type":"boolean","description":"Currently married"},"wedding_day":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Wedding date"},"date_formatted":{"type":"string","description":"Wedding date as text, for example July 4, 1995"},"age":{"type":"integer","description":"Age at the wedding"}},"required":["date","date_formatted","age"]},"spouse":{"allOf":[{"$ref":"#/components/schemas/Spouse"}]}},"required":["married"],"description":"Marriage"},"Housing":{"type":"object","properties":{"owns":{"type":"boolean","description":"Owns their home"},"type":{"type":"string","enum":["House","Apartment","Condo","Townhouse","Mobile Home","Farmhouse"],"description":"Kind of home"},"status":{"type":"string","enum":["Homeowner","Renter"],"description":"Tenure"}},"required":["owns","type","status"],"description":"Home"},"Pets":{"type":"object","properties":{"has_pets":{"type":"boolean","description":"Has at least one pet"},"pets":{"type":"array","items":{"type":"string","enum":["Dog","Cat","Fish","Bird","Small Animal","Reptile"]},"description":"Kinds of pets"},"dog_count":{"description":"Number of dogs, when pets includes Dog","type":"integer"},"cat_count":{"description":"Number of cats, when pets includes Cat","type":"integer"}},"required":["has_pets","pets"],"description":"Pets"},"Veteran":{"type":"object","properties":{"is_veteran":{"type":"boolean","description":"Served in the US military"},"branch":{"description":"Branch, veterans only","type":"string","enum":["Army","Navy","Air Force","Marines","Coast Guard"]},"service_period":{"description":"Era of service, veterans only","type":"string","enum":["World War II","Korean War","Vietnam Era","Gulf War Era I","Gulf War Era II"]}},"required":["is_veteran"],"description":"Military service"},"SocialMedia":{"type":"object","properties":{"uses_social_media":{"type":"boolean","description":"Uses at least one platform"},"platforms":{"type":"array","items":{"type":"string","enum":["Facebook","YouTube","Instagram","TikTok","Snapchat","LinkedIn","X","Reddit","Pinterest"]},"description":"Platforms used"},"platform_count":{"type":"integer","description":"Number of platforms used"}},"required":["uses_social_media","platforms","platform_count"],"description":"Social media"},"Vehicles":{"type":"object","properties":{"has_vehicle":{"type":"boolean","description":"Household has a vehicle"},"count":{"type":"integer","description":"Vehicles owned"},"primary_transport":{"type":"string","enum":["Personal Vehicle","Public Transit"],"description":"Main way of getting around"}},"required":["has_vehicle","count","primary_transport"],"description":"Vehicles"},"Phone":{"type":"object","properties":{"phone":{"type":"boolean","description":"Has a mobile phone"},"number":{"description":"Fictional number in the 555-01xx range","type":"string"},"smartphone":{"type":"object","properties":{"OS":{"type":"string","enum":["iOS","Android"],"description":"Phone operating system"},"Brand":{"type":"string","description":"Phone maker"},"model":{"type":"string","description":"Phone model"}},"required":["OS","Brand","model"]},"carrier":{"type":"string","description":"Mobile carrier"}},"required":["phone","smartphone","carrier"],"description":"Phone"},"Email":{"type":"object","properties":{"status":{"type":"boolean","description":"Has an email address"},"address":{"type":"string","description":"Address on a reserved example domain, never deliverable"}},"required":["status","address"],"description":"Email"},"Personality":{"type":"object","properties":{"bigFive":{"type":"object","properties":{"openness":{"type":"integer","minimum":0,"maximum":100,"description":"Openness to experience, 0 to 100"},"conscientiousness":{"type":"integer","minimum":0,"maximum":100,"description":"Conscientiousness, 0 to 100"},"extraversion":{"type":"integer","minimum":0,"maximum":100,"description":"Extraversion, 0 to 100"},"agreeableness":{"type":"integer","minimum":0,"maximum":100,"description":"Agreeableness, 0 to 100"},"neuroticism":{"type":"integer","minimum":0,"maximum":100,"description":"Neuroticism, 0 to 100"}},"required":["openness","conscientiousness","extraversion","agreeableness","neuroticism"]}},"required":["bigFive"],"description":"Big Five personality scores"},"Tendencies":{"type":"object","properties":{"musicGenres":{"type":"array","items":{"type":"string"},"description":"Favorite music genres"},"podcastAffinity":{"type":"integer","minimum":0,"maximum":100,"description":"How likely they are to listen to podcasts, 0 to 100"},"drinking":{"type":"object","properties":{"drinking":{"type":"boolean","description":"Drinks alcohol"}},"required":["drinking"]}},"required":["musicGenres","podcastAffinity","drinking"],"description":"Habits and tastes"},"TimelineEvent":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Event date, YYYY-MM-DD"},"message":{"type":"string","description":"What happened"}},"required":["date","message"]},"Meta":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"number"}},"required":["version"]},"copyright":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"engine":{"type":"string","enum":["local","upstream"],"description":"Which generator answered"},"dataset":{"type":"string","description":"Reference dataset version the seed is reproducible against"}},"required":["jsonapi","copyright","authors","engine","dataset"]}}}}