Quick Start

Get started with the Python SDK in minutes.

Installation

First, install the SDK:

pip install syntheticusers

Initialize the Client

import syntheticusers
from syntheticusers import (
    ApiClient,
    Configuration,
    StudiesApi,
    AudiencesApi,
    SummariesApi
)

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

# Create API client context
with ApiClient(configuration) as api_client:
    # Use API client for all operations
    pass

Complete Workflow Example

Here's a complete example showing the core workflow: create an audience, generate synthetic users, run interviews, and analyze results.

import syntheticusers
from syntheticusers import (
    ApiClient,
    Configuration,
    AudiencesApi,
    StudiesApi,
    SummariesApi
)

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

with ApiClient(configuration) as api_client:
    # Initialize API instances
    audiences_api = AudiencesApi(api_client)
    studies_api = StudiesApi(api_client)
    summaries_api = SummariesApi(api_client)
    
    # Step 1: Generate an audience with synthetic users
    print("Generating audience...")
    audience = audiences_api.generate_audience_v1(
        project_id="your-project-id",
        audience_generate={
            "name": "Mobile App Users",
            "description": "Tech-savvy users aged 25-40 who frequently use mobile apps",
            "size": 10
        }
    )
    print(f"✓ Created audience: {audience.id}")
    
    # Step 2: Create a research study
    print("Creating study...")
    study = studies_api.create_study_v1(
        project_id="your-project-id",
        study_create={
            "description": "Validate new app navigation design",
            "audience_ids": [audience.id]
        }
    )
    print(f"✓ Created study: {study.id}")
    
    # Step 3: Conduct interviews
    print("Running interviews...")
    studies_api.interview_v1(
        project_id="your-project-id",
        study_id=study.id,
        interview_request={
            "message": "How do you typically navigate mobile apps? What frustrates you most?"
        }
    )
    print("✓ Interviews started")
    
    # Step 4: Generate insights summary
    print("Generating insights...")
    summary = studies_api.generate_summary_v1(
        project_id="your-project-id",
        study_id=study.id,
        summary_create={
            "title": "Navigation Research Findings",
            "description": "Key insights from user interviews"
        }
    )
    print(f"✓ Generated summary: {summary.id}")
    
    # Step 5: Ask follow-up questions
    print("Asking follow-up questions...")
    response = summaries_api.summary_follow_up_v1(
        project_id="your-project-id",
        summary_id=summary.id,
        summary_follow_up_request={
            "message": "What were the top 3 pain points users mentioned?"
        }
    )
    print(f"\nInsights: {response.answer}")

Configuration Options

Using Environment Variables

export SYNTHETICUSERS_API_TOKEN="your-access-token"

import os
from syntheticusers import Configuration

configuration = Configuration(
    host="https://api.syntheticusers.com/api/v1",
    access_token=os.getenv("SYNTHETICUSERS_API_TOKEN")
)

Custom Configuration

from syntheticusers import Configuration

configuration = Configuration(
    host="https://api.syntheticusers.com/api/v1",
    access_token="your-access-token",
    # Optional: Add custom headers
    api_key={"X-Custom-Header": "value"},
    # Optional: Configure timeouts
    timeout=30
)

Error Handling

from syntheticusers import ApiClient, Configuration, StudiesApi
from syntheticusers.exceptions import ApiException

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

try:
    with ApiClient(configuration) as api_client:
        studies_api = StudiesApi(api_client)
        
        study = studies_api.create_study_v1(
            project_id="your-project-id",
            study_create={"description": "My study"}
        )
        
except ApiException as e:
    print(f"API Error: {e.status} - {e.reason}")
    print(f"Response body: {e.body}")
except Exception as e:
    print(f"Unexpected error: {e}")

Common Operations

List Resources

from syntheticusers import ProjectsApi, StudiesApi

with ApiClient(configuration) as api_client:
    # List all projects
    projects_api = ProjectsApi(api_client)
    projects = projects_api.list_projects_v1(
        workspace_id="your-workspace-id"
    )
    
    # List studies in a project
    studies_api = StudiesApi(api_client)
    studies = studies_api.list_studies_v1(
        project_id="your-project-id"
    )

Export Data

from syntheticusers import StudiesApi, SummariesApi

with ApiClient(configuration) as api_client:
    studies_api = StudiesApi(api_client)
    summaries_api = SummariesApi(api_client)
    
    # Download study as PDF
    pdf_content = studies_api.get_study_pdf_v1(
        project_id="your-project-id",
        study_id="your-study-id"
    )
    
    with open("study.pdf", "wb") as f:
        f.write(pdf_content)
    
    # Export summary
    summary_pdf = summaries_api.export_summary_v1(
        project_id="your-project-id",
        summary_id="your-summary-id",
        format="pdf"
    )
    
    with open("summary.pdf", "wb") as f:
        f.write(summary_pdf)

Next Steps

• Core Concepts - Understand the data model
• Complete Guide - Step-by-step walkthrough
• API Reference - Full method documentation
• Common Tasks - Quick links to key methods