Skip to Content
Persona Structure

Persona Structure

Complete reference for the PersonaGen persona data structure. Every generated persona contains 62 precisely defined dimensions across demographics, psychology, lifestyle, and physical attributes.

Overview

PersonaGen generates comprehensive synthetic personas with:

  • 62 dimensions across 13 hierarchical tiers
  • 10^114 unique combinations across all dimensions and values
  • Research-backed correlations from Census Bureau, BLS, and academic sources
  • Deterministic generation - same seed always produces identical persona

Hierarchical Generation: Dimensions are generated in dependency order across 13 tiers, ensuring realistic correlations between characteristics like education → occupation → income.

Response Structure

Every persona response follows this consistent JSON structure:

{
  "success": true,
  "data": {
    "name": {
      "first_name": "Sarah",
      "last_name": "Chen"
    },
    "demographics": {
      /* 18 dimensions */
    },
    "psychology": {
      /* 7 dimensions */
    },
    "lifestyle": {
      /* 25 dimensions */
    },
    "physical": {
      /* 12 dimensions */
    }
  },
  "metadata": {
    "id": "persona_1234567890",
    "version": "1.0",
    "generated_at": "2025-01-09T10:30:00Z",
    "seed": "custom_seed_123",
    "usage": {
      "requests_remaining": 999,
      "reset_date": "2025-02-01T00:00:00Z"
    }
  }
}

Demographics (18 dimensions)

Core demographic characteristics and socioeconomic background.

Foundational Demographics

gender

Gender identity categories reflecting contemporary demographic research.

Possible Values:

  • male, female, non_binary
  • transgender_male, transgender_female
  • genderfluid, agender

ethnicity

US ethnicity categories with meaningful regional distinctions, aligned with Census Bureau data.

Possible Values:

  • white - European ancestry
  • hispanic_latino - Mexican, Puerto Rican, Cuban, Central/South American
  • black_american - African American (descendants of slavery)
  • black_caribbean - Jamaican, Haitian, Dominican immigrants
  • black_african - Nigerian, Ethiopian, Ghanaian immigrants
  • east_asian - Chinese, Korean, Japanese
  • southeast_asian - Filipino, Vietnamese, Thai, Indonesian
  • south_asian - Indian, Pakistani, Bangladeshi, Sri Lankan
  • native_american - Indigenous, Alaska Native
  • middle_eastern_north_african - Arab, Persian, Turkish
  • pacific_islander - Hawaiian, Samoan
  • multiracial - Two or more races

age

Age as specific integer (18-95+) calculated from birth year.

Additional Fields:

  • birth_year - Calculated birth year (e.g., 1995)
  • birthday - Generated birthday in YYYY-MM-DD format (e.g., “1995-03-15”)

country_of_birth

Country of birth reflecting top immigrant populations to US from Census Bureau data.

Possible Values:

  • North America: united_states, mexico, canada, el_salvador, guatemala, cuba, dominican_republic
  • Asia: china, india, philippines, vietnam, south_korea, japan, pakistan, iran
  • Europe: united_kingdom, germany, russia, poland, ukraine, italy
  • South America: colombia, brazil, venezuela, peru
  • Africa & Middle East: nigeria, ethiopia, egypt, somalia
  • other_country

immigration_status

Immigration generation status using Census data categories.

Possible Values:

  • us_born_third_generation_plus - US-born, grandparents also US-born
  • us_born_second_generation - US-born, parents foreign-born
  • first_generation_naturalized - Foreign-born, US citizen
  • first_generation_permanent_resident - Foreign-born, green card holder
  • first_generation_recent_immigrant - Foreign-born, recent arrival
  • refugee_asylum_status - Refugee or asylum status
  • mixed_status_family - Mixed immigration status within family

location

US state of residence (alphabetical listing of all 50 states plus Puerto Rico).

Possible Values: alabama, alaska, arizona, arkansas, california, colorado, connecticut, delaware, florida, georgia, hawaii, idaho, illinois, indiana, iowa, kansas, kentucky, louisiana, maine, maryland, massachusetts, michigan, minnesota, mississippi, missouri, montana, nebraska, nevada, new_hampshire, new_jersey, new_mexico, new_york, north_carolina, north_dakota, ohio, oklahoma, oregon, pennsylvania, rhode_island, south_carolina, south_dakota, tennessee, texas, utah, vermont, virginia, washington, west_virginia, wisconsin, wyoming, puerto_rico

geographic_context

Geographic setting using Census Bureau urban-rural classifications.

Possible Values:

  • major_metropolitan - Large metro areas (1M+ people)
  • metropolitan_urban - Mid-size cities and urban areas
  • suburban - Suburban areas of all income levels
  • small_city - Cities under 50K people
  • small_town - Towns under 10K people
  • rural - Rural areas, farms, isolated communities
  • special_community - Military base, reservation, border area
  • college_town - University-centered communities

Intergenerational Background

parents_education

Highest education level of parents, using same categories as personal education.

Possible Values:

  • less_than_high_school, high_school_graduate, some_college_no_degree
  • associate_degree, bachelor_degree, master_degree
  • professional_degree, doctoral_degree

childhood_ses

Socioeconomic status during childhood years.

Possible Values:

  • poverty, working_class, lower_middle, middle_class, upper_middle, wealthy

Personal Demographics

education

Personal education level aligned with Census Bureau Educational Attainment categories.

Possible Values:

  • less_than_high_school - Includes elementary/middle school incomplete
  • high_school_graduate - High school diploma or equivalent
  • some_college_no_degree - Some college but no degree
  • associate_degree - Associate’s degree (2-year)
  • bachelor_degree - Bachelor’s degree (4-year)
  • master_degree - Master’s degree
  • professional_degree - JD, MD, etc.
  • doctoral_degree - PhD, EdD, etc.

occupational_background

Professional background aligned with BLS Major Occupational Groups.

Possible Values:

  • Technology & Engineering: technology_computing, engineering_technical
  • Healthcare & Sciences: healthcare_medical, science_research
  • Education: education_teaching
  • Business: business_finance, management_leadership
  • Legal & Public Service: legal_professional, public_safety_security
  • Arts & Media: arts_creative_media, sales_marketing
  • Service Industries: service_hospitality, personal_care_services
  • Skilled Trades: skilled_trades_construction, manufacturing_production, transportation_logistics
  • Other: agriculture_natural_resources, administrative_clerical, social_community_services, religious_clergy, military_veteran, homemaker_caregiver

employment_status

Current employment status using BLS categories.

Possible Values:

  • employed_full_time, employed_part_time, self_employed
  • unemployed_looking, unemployed_not_looking
  • retired, student, homemaker, unable_to_work, military_active

income

Household income brackets using Census Bureau categories (2023 data).

Possible Values:

  • under_25k - Under $25,000 (poverty/very low income)
  • 25k_to_50k - $25,000-$49,999 (low income)
  • 50k_to_75k - $50,000-$74,999 (lower middle class)
  • 75k_to_100k - $75,000-$99,999 (middle class)
  • 100k_to_150k - $100,000-$149,999 (upper middle class)
  • 150k_to_200k - $150,000-$199,999 (upper class)
  • over_200k - $200,000+ (high income)

languages

Languages spoken (multi-value array based on Census language data).

Possible Values: english, spanish, chinese, tagalog, vietnamese, arabic, french, korean, russian, german, haitian_creole, hindi, portuguese, italian, polish, japanese, persian, urdu, gujarati, other_language

english_proficiency

English language proficiency level using TESOL 4-level standard.

Possible Values:

  • native_speaker - Born into English-speaking environment
  • advanced - Near-native fluency, academic/professional use
  • intermediate - Conversational ability, some academic gaps
  • beginning - Basic survival English, needs significant support

Psychology (7 dimensions)

Cognitive abilities and personality traits based on validated psychological research.

Cognitive Profile

iq

IQ score as integer value sampled from normal distribution (mean=100, SD=15).

Range: 65-155+ (follows population distribution curve)

literacy_level

Reading and writing ability using NAAL (National Assessment of Adult Literacy) standard.

Possible Values:

  • below_basic - Cannot perform simple literacy activities
  • basic - Can perform simple, everyday literacy activities
  • intermediate - Can perform moderately challenging literacy activities
  • proficient - Can perform complex and challenging literacy activities

Big Five Personality Traits

Based on validated psychological research using 5-point scales for each trait.

big_five_openness

Openness to experience, creativity, intellectual curiosity.

Possible Values:

  • low_openness - Conventional, practical, prefers routine
  • below_average_openness - Traditional, down-to-earth, conservative
  • average_openness - Balanced between routine and novelty
  • above_average_openness - Appreciates art/beauty, curious
  • high_openness - Creative, curious, open to new experiences

big_five_conscientiousness

Organization, self-discipline, goal-directed behavior.

Possible Values:

  • low_conscientiousness - Disorganized, impulsive, procrastinating
  • below_average_conscientiousness - Spontaneous, flexible, less structured
  • average_conscientiousness - Reasonably organized and reliable
  • above_average_conscientiousness - Well-organized, generally dependable
  • high_conscientiousness - Very organized, dependable, disciplined

big_five_extraversion

Social energy, assertiveness, positive emotions.

Possible Values:

  • low_extraversion - Introverted, quiet, reserved, prefers solitude
  • below_average_extraversion - Somewhat introverted
  • average_extraversion - Ambivert, balanced social energy
  • above_average_extraversion - Outgoing, enjoys social situations
  • high_extraversion - Very outgoing, sociable, energetic

big_five_agreeableness

Compassion, cooperation, trust in others.

Possible Values:

  • low_agreeableness - Competitive, skeptical, independent
  • below_average_agreeableness - Somewhat competitive, critical
  • average_agreeableness - Balanced cooperation/competition
  • above_average_agreeableness - Generally cooperative, trusting
  • high_agreeableness - Very cooperative, trusting, helpful

big_five_neuroticism

Emotional stability, stress resilience, anxiety levels.

Possible Values:

  • low_neuroticism - Emotionally stable, resilient, calm
  • below_average_neuroticism - Generally stable, occasional stress
  • average_neuroticism - Moderate emotional reactivity
  • above_average_neuroticism - Somewhat anxious, stress-prone
  • high_neuroticism - Anxious, emotionally unstable

Lifestyle (25 dimensions)

Personal choices, relationships, living situation, and lifestyle preferences.

Identity & Relationships

sexual_orientation

Sexual orientation using standard demographic categories.

Possible Values:

  • heterosexual, gay, lesbian, bisexual, pansexual
  • asexual, demisexual, queer, questioning

relationship_status

Current relationship status.

Possible Values:

  • single_never_married, married, divorced, widowed, separated
  • domestic_partnership, long_term_relationship

number_of_children

Number of children as integer value.

Range: 0-8+ (integer, e.g., 0, 1, 2, 3)

religious_identity

Religious affiliation aligned with Pew Research major categories.

Possible Values:

  • christian_protestant, christian_catholic, christian_other
  • jewish, muslim, other_religious
  • non_religious, spiritual_not_religious

political_leaning

Political orientation based on Pew Research political typology.

Possible Values:

  • progressive_left - Consistently liberal across all issues
  • establishment_liberal - Liberal but more mainstream Democratic
  • democratic_mainstay - Solid Democratic voters
  • outsider_left - Liberal but anti-establishment
  • stressed_sideliners - Disengaged, mixed views
  • ambivalent_right - Conservative but not consistently
  • committed_conservative - Reliable Republican voters
  • populist_right - Trump-style populism
  • libertarian - Fiscally conservative, socially liberal
  • apolitical_disengaged - No political interest or involvement

Life Experience (Boolean Dimensions)

These are yes/no characteristics based on life experiences:

has_pets

Values: true, false

has_criminal_history

Values: true, false

has_been_married

Values: true, false

has_been_divorced

Values: true, false

has_military_experience

Values: true, false

Living Situation

homeownership_status

Housing tenure using Census Bureau categories.

Possible Values:

  • own_outright - Owned free and clear (no mortgage)
  • own_with_mortgage - Owned with mortgage or loan
  • rent_market_rate - Renting at market rate
  • rent_subsidized - Renting with assistance (Section 8, etc.)
  • occupancy_no_rent - Living in family property, caretaking
  • transitional_housing - Temporary/transitional housing, shelters

housing_type

Type of housing unit using Census Bureau categories.

Possible Values:

  • single_family_house, apartment, condominium, townhouse
  • mobile_home, group_quarters, temporary_housing

primary_transportation_method

Primary method of transportation for daily activities.

Possible Values:

  • personal_vehicle - Own/family car, truck, SUV, motorcycle
  • public_transit - Bus, subway, light rail, commuter train
  • walking - Walking as primary transportation method
  • bicycle - Bicycle, e-bike as primary transportation method

activity_level

Physical activity level based on CDC Physical Activity Guidelines.

Possible Values:

  • inactive - Less than 10 minutes per week of moderate activity
  • insufficiently_active - Some activity but less than 150 minutes/week moderate
  • meets_guidelines - 150-300 minutes/week moderate or 75-150 vigorous
  • exceeds_guidelines - More than 300 minutes/week moderate or 150 vigorous
  • highly_active - Athletic training level, daily intense exercise

debt_level

Total debt amount using consistent categorization.

Possible Values:

  • no_debt, under_5k, 5k_to_25k, 25k_to_50k
  • 50k_to_100k, 100k_to_200k, over_200k

technology_comfort

Technology comfort and usage level.

Possible Values:

  • tech_averse - Avoids technology, prefers traditional methods
  • basic_user - Uses basic functions like email, calls, simple apps
  • comfortable_user - Regular use of common apps and services
  • advanced_user - Customizes settings, uses advanced features
  • power_user - Deep technical knowledge, early adopter

Multi-Value Lifestyle Dimensions

interests

Personal interests and hobbies (multi-value array with 529 possible values).

Categories Include:

  • Technology & Computing: programming_hobby, web_development_hobby, cryptocurrency_trading, 3d_printing, etc.
  • Fitness & Sports: running, cycling, swimming, basketball, tennis, yoga, crossfit, etc.
  • Arts & Crafts: painting, photography, music (piano, guitar, singing), crafts (sewing, knitting), etc.
  • Entertainment: movies, television, podcasts, music_listening, concerts, etc.
  • Outdoor Activities: hiking, camping, fishing, gardening, birdwatching, etc.
  • Learning & Culture: reading, language_learning, museums, travel, cooking, etc.
  • Gaming: video_gaming, board_games, chess, card_games, tabletop_rpgs, etc.
  • Social & Community: volunteering, community_service, social_clubs, networking, etc.

Interest Selection: Number of interests varies based on demographic correlations, typically 6-15 interests per persona.

dietary_restrictions

Dietary restrictions and preferences (multi-value array).

Possible Values:

  • vegetarian, vegan, gluten_free, dairy_free
  • halal, kosher, low_sodium, diabetic_diet
  • keto, paleo, mediterranean, food_allergies

health_conditions

Current health conditions (multi-value array based on CDC prevalence data).

Possible Values:

  • diabetes, hypertension, heart_disease, respiratory_condition
  • chronic_pain, mental_health_condition, autoimmune_condition
  • active_cancer, cancer_survivor, obesity

Physical (12 dimensions)

Physical characteristics and appearance traits.

Body Characteristics

height

Physical height with multiple format representations.

Structure:

{
  "cm": 174,
  "feet_and_inches": "5'9\""
}

Height Generation: Sampled from population distribution curves (Male: mean=176cm, SD=7; Female: mean=162cm, SD=7)

weight

Physical weight with multiple format representations and calculated BMI.

Structure:

{
  "kg": 91,
  "lbs": 201,
  "bmi": 30.1
}

body_build

Overall body type and build.

Possible Values:

  • very_slim - Underweight, very lean frame
  • slim - Lean, minimal body fat
  • average - Normal weight, balanced proportions
  • athletic - Muscular, toned, fit
  • stocky - Broad frame, dense build
  • overweight - Above normal weight
  • obese - Significantly above normal weight

skin_tone

Skin color and tone across diverse ethnicities.

Possible Values:

  • porcelain - Porcelain, ivory, very fair
  • fair - Fair, light beige, peachy
  • light_tan - Light tan, golden beige
  • beige - Medium beige, honey, golden
  • tan - Tan, caramel, bronze
  • olive - All olive undertones (light to dark)
  • brown - Deep tan, rich brown, mahogany
  • dark_brown - Dark brown, chocolate, deep bronze
  • ebony - Deep brown, ebony, very dark

Hair Characteristics

hair (Object)

Hair characteristics including color and texture.

Structure:

{
  "color": "dark_brown",
  "texture": "type_1_straight"
}

Hair Colors:

  • black, dark_brown, medium_brown, light_brown
  • dirty_blonde, blonde, platinum_blonde, strawberry_blonde
  • red, auburn, copper
  • silver, gray, white, dyed_unnatural

Hair Textures:

  • type_1_straight - All straight hair
  • type_2a_wavy_loose - Loose waves
  • type_2b_wavy_defined - More defined waves
  • type_2c_wavy_strong - Strong waves
  • type_3a_curly_loose - Large, loose curls
  • type_3b_curly_tight - Springy curls
  • type_3c_curly_coarse - Tight curls
  • type_4_coily - Coils and kinks

Eyes & Facial Features

eyes (Object)

Eye characteristics including color and shape.

Structure:

{
  "color": "medium_brown",
  "shape": "downturned"
}

Eye Colors:

  • dark_brown, medium_brown, light_brown, amber
  • hazel_brown, hazel_green, green, blue_green
  • light_blue, medium_blue, dark_blue, gray_blue, gray

Eye Shapes:

  • almond - Most common globally, oval shape
  • round - Circular, open appearance
  • hooded - Heavy upper lid covers crease
  • monolid - No visible crease (East Asian genetic trait)
  • upturned - Outer corners higher (cat-eye)
  • downturned - Outer corners lower

nose_shape

Nose shape characteristics.

Possible Values:

  • straight - Classic straight bridge
  • button - Small, upturned, cute
  • roman - Prominent bridge, aquiline
  • wide - Broad, flat bridge
  • narrow - Thin, pinched, sharp

face_shape

Overall face shape.

Possible Values:

  • oval, round, square, rectangular_oblong
  • heart_inverted_triangle, diamond, triangular_pear, long_narrow

Clothing Sizes

clothing_sizes (Object)

Clothing size information across categories.

Structure:

{
  "shirt_size": "XXL",
  "pant_size": "44",
  "shoe_size_us": "8.5"
}

Physical Description

physical_description

Natural language summary of physical appearance.

Example: “A middle-aged male, 5 feet 9 inches tall, with a heavyset build, straight dark brown hair, downturned medium brown eyes, and porcelain skin.”

Generation Metadata

Every persona includes comprehensive metadata about generation details.

Response Metadata

id

Unique persona identifier in format persona_[timestamp].

version

API version used for generation.

generated_at

ISO 8601 timestamp of persona generation.

seed

Seed value used for deterministic generation. Custom seeds or auto-generated.

usage

Usage information for your API key.

Structure:

{
  "requests_remaining": 999,
  "reset_date": "2025-02-01T00:00:00Z"
}

Example Complete Persona

{
  "success": true,
  "data": {
    "name": {
      "first_name": "Maria",
      "last_name": "Rodriguez"
    },
    "demographics": {
      "gender": "female",
      "ethnicity": "hispanic_latino",
      "country_of_birth": "mexico",
      "immigration_status": "first_generation_naturalized",
      "location": "california",
      "geographic_context": "major_metropolitan",
      "parents_education": "high_school_graduate",
      "childhood_ses": "working_class",
      "education": "bachelor_degree",
      "occupational_background": "healthcare_medical",
      "employment_status": "employed_full_time",
      "income": "75k_to_100k",
      "languages": ["english", "spanish"],
      "english_proficiency": "advanced",
      "age": 29,
      "birth_year": 1995,
      "birthday": "1995-03-15"
    },
    "psychology": {
      "literacy_level": "proficient",
      "big_five_openness": "above_average_openness",
      "big_five_conscientiousness": "high_conscientiousness",
      "big_five_extraversion": "average_extraversion",
      "big_five_agreeableness": "high_agreeableness",
      "big_five_neuroticism": "below_average_neuroticism",
      "iq": 108
    },
    "lifestyle": {
      "sexual_orientation": "heterosexual",
      "relationship_status": "married",
      "number_of_children": 1,
      "religious_identity": "christian_catholic",
      "political_leaning": "democratic_mainstay",
      "has_pets": false,
      "has_criminal_history": false,
      "has_been_married": true,
      "has_been_divorced": false,
      "has_military_experience": false,
      "homeownership_status": "rent_market_rate",
      "housing_type": "apartment",
      "activity_level": "meets_guidelines",
      "debt_level": "25k_to_50k",
      "technology_comfort": "comfortable_user",
      "primary_transportation_method": "personal_vehicle",
      "dietary_restrictions": [],
      "health_conditions": [],
      "interests": [
        "cooking",
        "international_cooking",
        "family_time",
        "movies",
        "music_listening",
        "healthcare_advocacy",
        "community_volunteering"
      ]
    },
    "physical": {
      "skin_tone": "tan",
      "body_build": "average",
      "nose_shape": "straight",
      "face_shape": "oval",
      "hair": {
        "color": "dark_brown",
        "texture": "type_2a_wavy_loose"
      },
      "eyes": {
        "color": "dark_brown",
        "shape": "almond"
      },
      "height": {
        "cm": 158,
        "feet_and_inches": "5'2\""
      },
      "weight": {
        "kg": 65,
        "lbs": 143,
        "bmi": 26.0
      },
      "clothing_sizes": {
        "shirt_size": "M",
        "pant_size": "10",
        "shoe_size_us": "7"
      },
      "physical_description": "A young adult female, 5 feet 2 inches tall, with an average build, wavy dark brown hair, almond-shaped dark brown eyes, and tan skin."
    }
  },
  "metadata": {
    "id": "persona_1704812345678",
    "version": "1.0", 
    "generated_at": "2025-01-09T14:32:25.678Z",
    "seed": "example_maria_rodriguez",
    "usage": {
      "requests_remaining": 998,
      "reset_date": "2025-02-01T00:00:00Z"
    }
  }
}

Research Use Only: Personas are statistical models for research and development. They represent population patterns, not stereotypes, and should not be used for individual profiling or decision-making.

Last updated on
API ReferenceDashboard Guide