Conducting Your First User Research Study

A complete walkthrough from setup to insights.

Overview

This guide walks you through conducting your first research study with Synthetic Users. You'll learn to create a project, define an audience, generate synthetic users, run interviews, and analyze results.

Time required: 15-20 minutes
Prerequisites: API access token (Authentication Guide)

Step 1: Set Up Your Research Environment

Create a Workspace (via UI)

First-time users should create a workspace through the web interface at https://app.syntheticusers.com. Workspaces manage billing, team members, and organizational settings.

Create a Project

Projects organize related research studies. Create one for your initiative:

# Python
from syntheticusers import ApiClient, Configuration, ProjectsApi

configuration = Configuration(
    host="https://api.syntheticusers.com/api/v1",
    access_token="your-access-token"
)

with ApiClient(configuration) as api_client:
    projects_api = ProjectsApi(api_client)
    
    project = projects_api.create_project_v1(
        workspace_id="your-workspace-id",
        project_create={
            "name": "Mobile App Redesign Research",
            "description": "User research for Q1 2026 app redesign"
        }
    )
    
    project_id = project.id
    print(f"Created project: {project_id}")

// TypeScript
import { createConfiguration, ProjectsApi } from '@syntheticusers/sdk'

const config = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  }
})

const projectsApi = new ProjectsApi(config)

const project = await projectsApi.createProjectV1({
  workspaceId: 'your-workspace-id',
  projectCreate: {
    name: 'Mobile App Redesign Research',
    description: 'User research for Q1 2026 app redesign'
  }
})

const projectId = project.id
console.log(`Created project: ${projectId}`)

Create projects using the Projects API.

Step 2: Define Your Target Audience

Generate an Audience

Let AI create diverse synthetic user personas based on your target demographic:

# Python
from syntheticusers import AudiencesApi

audiences_api = AudiencesApi(api_client)

audience = audiences_api.generate_audience_v1(
    project_id=project_id,
    audience_generate={
        "name": "Mobile Power Users",
        "description": "Tech-savvy professionals aged 25-45 who use mobile apps daily for productivity and entertainment. Mix of iOS and Android users.",
        "size": 10  # Generate 10 synthetic users
    }
)

audience_id = audience.id
print(f"Generated audience: {audience_id}")

// TypeScript
import { AudiencesApi } from '@syntheticusers/sdk'

const audiencesApi = new AudiencesApi(config)

const audience = await audiencesApi.generateAudienceV1({
  projectId: projectId,
  audienceGenerate: {
    name: 'Mobile Power Users',
    description: 'Tech-savvy professionals aged 25-45 who use mobile apps daily for productivity and entertainment. Mix of iOS and Android users.',
    size: 10  // Generate 10 synthetic users
  }
})

const audienceId = audience.id
console.log(`Generated audience: ${audienceId}`)

Use generate_audience for AI-powered audience generation.

Alternative: Use create_audience to manually define audience attributes, then generate users separately.

Review Synthetic Users

List the generated synthetic users to verify personas:

# Python
users = audiences_api.list_synthetic_users_v1(
    project_id=project_id,
    audience_id=audience_id
)

for user in users:
    print(f"- {user.name}: {user.description}")

Synthetic users are accessible via the Audiences API.

Step 3: Create Your Research Study

Define Problems and Solutions (Optional)

For structured research, define what you're investigating:

# Python
from syntheticusers import ProblemsApi, SolutionsApi

problems_api = ProblemsApi(api_client)
solutions_api = SolutionsApi(api_client)

# Define the problem
problem = problems_api.create_problem_v1(
    project_id=project_id,
    problem_create={
        "title": "Users struggle with navigation",
        "description": "Current navigation is confusing and requires too many taps to reach key features"
    }
)

# Define the solution to test
solution = solutions_api.create_solution_v1(
    project_id=project_id,
    solution_create={
        "title": "Bottom Tab Navigation",
        "description": "Implement bottom tab bar with 5 primary sections for quick access"
    }
)

Use the Problems and Solutions APIs to define research context.

Create the Study

Now create a study that ties everything together:

# Python
from syntheticusers import StudiesApi

studies_api = StudiesApi(api_client)

study = studies_api.create_study_v1(
    project_id=project_id,
    study_create={
        "description": "Validate new bottom navigation design with mobile power users",
        "audience_ids": [audience_id],
        "problem_ids": [problem.id] if problem else [],
        "solution_ids": [solution.id] if solution else []
    }
)

study_id = study.id
print(f"Created study: {study_id}")

// TypeScript
import { StudiesApi } from '@syntheticusers/sdk'

const studiesApi = new StudiesApi(config)

const study = await studiesApi.createStudyV1({
  projectId: projectId,
  studyCreate: {
    description: 'Validate new bottom navigation design with mobile power users',
    audienceIds: [audienceId],
    problemIds: problem ? [problem.id] : [],
    solutionIds: solution ? [solution.id] : []
  }
})

const studyId = study.id
console.log(`Created study: ${studyId}`)

Use create_study to create studies.

Step 4: Conduct Interviews

Run Interviews

Start conversations with your synthetic users:

# Python
interview_result = studies_api.interview_v1(
    project_id=project_id,
    study_id=study_id,
    interview_request={
        "message": "Can you walk me through how you typically navigate mobile apps? What frustrates you most about app navigation?"
    }
)

print(f"Interviews started. Check status at study: {study_id}")

// TypeScript
const interviewResult = await studiesApi.interviewV1({
  projectId: projectId,
  studyId: studyId,
  interviewRequest: {
    message: 'Can you walk me through how you typically navigate mobile apps? What frustrates you most about app navigation?'
  }
})

console.log(`Interviews started. Check status at study: ${studyId}`)

Use interview to run interviews.

Ask Follow-up Questions

Dig deeper based on initial responses:

# Python
followup = studies_api.study_follow_up_v1(
    project_id=project_id,
    study_id=study_id,
    study_follow_up_request={
        "message": "How would you feel about having all primary features accessible from a bottom navigation bar?"
    }
)

Use study_follow_up to ask questions across all interviews, or interview_follow_up for individual interviews.

Step 5: Generate Insights

Create a Summary

Generate AI-powered analysis of all interviews:

# Python
summary = studies_api.generate_summary_v1(
    project_id=project_id,
    study_id=study_id,
    summary_create={
        "title": "Navigation Research Findings",
        "description": "Key insights from user interviews about navigation preferences"
    }
)

summary_id = summary.id
print(f"Generated summary: {summary_id}")

// TypeScript
import { SummariesApi } from '@syntheticusers/sdk'

const summary = await studiesApi.generateSummaryV1({
  projectId: projectId,
  studyId: studyId,
  summaryCreate: {
    title: 'Navigation Research Findings',
    description: 'Key insights from user interviews about navigation preferences'
  }
})

const summaryId = summary.id
console.log(`Generated summary: ${summaryId}`)

Use generate_summary to analyze interview data.

Visualize with Knowledge Graphs

Create a visual representation of relationships:

# Python
knowledge_graph = studies_api.generate_knowledge_graph_v1(
    project_id=project_id,
    study_id=study_id
)

print("Knowledge graph generated!")

Use generate_knowledge_graph to visualize insights.

Ask Questions About Your Summary

Use natural language to explore findings:

# Python
from syntheticusers import SummariesApi

summaries_api = SummariesApi(api_client)

answer = summaries_api.summary_follow_up_v1(
    project_id=project_id,
    summary_id=summary_id,
    summary_follow_up_request={
        "message": "What were the top 3 pain points users mentioned about navigation?"
    }
)

print(answer.response)

Use summary_follow_up to query your analysis.

Step 6: Export and Share

Generate a Professional Report

Create a comprehensive research document:

# Python
from syntheticusers import ReportsApi

reports_api = ReportsApi(api_client)

report = reports_api.create_report_v1(
    project_id=project_id,
    report_create={
        "title": "Mobile App Navigation Research Report",
        "description": "Findings from user interviews about navigation preferences and pain points",
        "study_ids": [study_id],
        "summary_ids": [summary_id]
    }
)

# Generate the full report content
full_report = reports_api.generate_full_report_v1(
    project_id=project_id,
    report_id=report.id
)

print(f"Report generated: {report.id}")

Use create_report and generate_full_report.

Download as PDF

Export for sharing with stakeholders:

# Python
pdf_content = studies_api.get_study_pdf_v1(
    project_id=project_id,
    study_id=study_id
)

with open("navigation-research.pdf", "wb") as f:
    f.write(pdf_content)

print("PDF exported successfully!")

Use get_study_pdf to download studies as PDFs.

Export Summary in Different Formats

# Python
# Export as text
text_export = summaries_api.export_summary_v1(
    project_id=project_id,
    summary_id=summary_id,
    format="txt"
)

# Export as PDF
pdf_export = summaries_api.export_summary_v1(
    project_id=project_id,
    summary_id=summary_id,
    format="pdf"
)

Use export_summary to export in multiple formats.

Best Practices

Audience Design

• Start with 10-15 synthetic users for initial research
• Use diverse demographics to avoid bias
• Extend audiences with extend_audience to test edge cases

Interview Questions

• Start with open-ended questions to gather rich insights
• Use follow-ups to probe specific areas
• Ask one topic at a time for clearer responses

Analysis

• Generate summaries after completing all interviews
• Use knowledge graphs to identify patterns
• Ask follow-up questions on summaries to explore specific themes

Workflow Efficiency

• Use stream_events to monitor progress in real-time
• Batch interview questions across all users with interview
• Create reusable audience templates for similar research

Troubleshooting

Interviews not starting?

• Verify the study has linked audiences
• Check that synthetic users were generated successfully
• Ensure your API token has the correct permissions

Empty summaries?

• Make sure interviews are completed before generating summaries
• Check that interview responses contain substantive content

Slow generation?

• Larger audiences (20+ users) take longer to interview
• Complex questions may require more processing time
• Use event streaming to monitor progress

Next Steps

• Generate Reports and Insights - Advanced analysis techniques
• Core Concepts - Deeper understanding of the platform
• Python SDK - Complete SDK documentation
• TypeScript SDK - Complete SDK documentation