End-to-End Example

This guide walks through the complete workflow of creating a case, uploading evidence, and generating a technical report using the Silent Witness REST API.

Overview

The typical workflow follows these steps:

1. Create an organization (if you don't have one)
2. Create a case with vehicles, occupants, and accident information
3. Upload vehicle damage photos
4. Link uploaded files to the plaintiff vehicle
5. Create a report (triggers delta-v calculation automatically)
6. Poll for completion and download the report

Prerequisites

• An API key from the Silent Witness dashboard
• Vehicle damage photos (JPEG or PNG)
• Case information (accident details, vehicle info, occupant data)

Step 1: Create an Organization

Organizations help you group cases by law firm or client.

curl -X POST "https://api.silentwitness.ai/api/organizations" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smith & Associates Law Firm",
    "phone_number": "555-123-4567",
    "street_address": "123 Main Street, Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "United States"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "org_abc123def456",
    "name": "Smith & Associates Law Firm"
  }
}

Save the org_abc123def456 for the next step.

Step 2: Create a Case with All Data

Create a case with vehicles, occupants, and accident information in a single request:

curl -X POST "https://api.silentwitness.ai/api/cases" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plaintiff_name": "John Smith",
    "defendant_name": "Bob Johnson",
    "attorney_name": "Jane Attorney, Esq.",
    "organization_id": "org_abc123def456",
    "analysis_type": "accident_injury",

    "accident": {
      "description": "Rear-end collision at red light. Defendant vehicle struck plaintiff vehicle from behind while plaintiff was stopped at intersection.",
      "date": "2024-01-10",
      "time": "14:30",
      "location": "123 Main St at Oak Ave, Los Angeles, CA"
    },

    "vehicles": [
      {
        "role": "plaintiff",
        "vehicle_maker": "Toyota",
        "vehicle_model": "Camry",
        "vehicle_year": "2020",
        "vehicle_vin": "4T1B11HK5LU123456",
        "vehicle_type": "sedan"
      },
      {
        "role": "defendant",
        "vehicle_maker": "Ford",
        "vehicle_model": "F-150",
        "vehicle_year": "2019",
        "vehicle_type": "truck"
      }
    ],

    "occupants": [
      {
        "name": "John Smith",
        "age": 45,
        "gender": "male",
        "height_inches": 70,
        "weight_lbs": 180,
        "position": "driver",
        "seatbelt_worn": true,
        "airbag_deployed": "yes",
        "alleged_injuries": ["cervical_spine", "lumbar_spine"],
        "injury_severity": "moderate"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "case": {
      "id": "case_xyz789abc123",
      "name": "Smith v. Johnson",
      "plaintiff_name": "John Smith"
    }
  }
}

Save the case_xyz789abc123 for subsequent steps.

Step 3: Upload Vehicle Damage Photos

Upload each damage photo. The API supports JPEG, PNG, and GIF images up to 50MB.

# Upload front damage photo
curl -X POST "https://api.silentwitness.ai/api/files/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@/path/to/front_damage.jpg" \
  -F "caseId=case_xyz789abc123" \
  -F "fileCategory=crash_analysis_plaintiff" \
  -F "vehicleIndex=0"

Response:

{
  "success": true,
  "data": {
    "fileId": "file_img001",
    "fileName": "front_damage.jpg",
    "status": "ready"
  }
}

Upload additional photos (rear, side, interior):

# Upload rear damage
curl -X POST "https://api.silentwitness.ai/api/files/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@/path/to/rear_damage.jpg" \
  -F "caseId=case_xyz789abc123" \
  -F "fileCategory=crash_analysis_plaintiff"

# Upload side damage
curl -X POST "https://api.silentwitness.ai/api/files/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@/path/to/side_damage.jpg" \
  -F "caseId=case_xyz789abc123" \
  -F "fileCategory=crash_analysis_plaintiff"

Collect all file IDs: file_img001, file_img002, file_img003

Step 4: Link Files to Plaintiff Vehicle

Update the case to link the uploaded images to the plaintiff vehicle:

curl -X PUT "https://api.silentwitness.ai/api/cases/case_xyz789abc123" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [
      {
        "role": "plaintiff",
        "image_file_ids": ["file_img001", "file_img002", "file_img003"]
      }
    ]
  }'

Step 5: Create a Report

Create a technical report. This automatically triggers delta-v calculation and biomechanics analysis:

curl -X POST "https://api.silentwitness.ai/api/reports" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "case_xyz789abc123",
    "type": "technical_report",
    "options": {
      "include_biomechanics": true
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "rpt_abc789xyz",
    "case_id": "case_xyz789abc123",
    "type": "technical_report",
    "status": "pending",
    "progress": {
      "message": "Starting analysis..."
    }
  }
}

Step 6: Poll for Completion

Poll the report status until it completes:

# Check status (repeat every 5 seconds)
curl "https://api.silentwitness.ai/api/reports/rpt_abc789xyz" \
  -H "X-API-Key: $API_KEY"

During processing:

{
  "success": true,
  "data": {
    "id": "rpt_abc789xyz",
    "status": "processing",
    "progress": {
      "current_step": "delta_v_calculation",
      "steps_completed": [],
      "message": "Calculating delta-v from damage photos..."
    }
  }
}

When completed:

{
  "success": true,
  "data": {
    "id": "rpt_abc789xyz",
    "status": "completed",
    "progress": {
      "current_step": "report_generation",
      "steps_completed": ["delta_v_calculation", "biomechanics_analysis", "report_generation"],
      "message": "Report generation complete"
    },
    "output": {
      "pdf_url": "https://storage.silentwitness.ai/reports/rpt_abc789xyz.pdf",
      "docx_url": "https://storage.silentwitness.ai/reports/rpt_abc789xyz.docx"
    }
  }
}

Step 7: Download the Report

Download the PDF or DOCX using the signed URLs:

# Download PDF
curl -o technical_report.pdf "https://storage.silentwitness.ai/reports/rpt_abc789xyz.pdf"

# Download DOCX
curl -o technical_report.docx "https://storage.silentwitness.ai/reports/rpt_abc789xyz.docx"

Note: Download URLs expire after 1 hour. Fetch a fresh URL by calling GET /api/reports/:id again.

Verify Results

You can verify the crash parameters were calculated by fetching the case:

curl "https://api.silentwitness.ai/api/cases/case_xyz789abc123" \
  -H "X-API-Key: $API_KEY" \
  | jq '.data.case.vehicles[0].crash_parameters'

{
  "delta_v_min": 8.5,
  "delta_v_max": 12.3,
  "delta_v_method": "ml",
  "pdof_degrees": 180,
  "crash_pulse_min_ms": 12,
  "crash_pulse_max_ms": 100,
  "calculated_at": "2024-01-15T12:00:00Z"
}

Complete Workflow Summary

1. POST /api/organizations        → Create organization (optional)
2. POST /api/cases                → Create case with all data
3. POST /api/files/upload         → Upload damage photos (repeat per file)
4. PUT /api/cases/:id             → Link file IDs to plaintiff vehicle
5. POST /api/reports              → Create report (starts async processing)
6. GET /api/reports/:id           → Poll until status is "completed"
7. Download PDF/DOCX              → Use signed URLs from output

Testing with Demo Data

For SDK testing without ML processing, use the use_demo_data option:

curl -X POST "https://api.silentwitness.ai/api/reports" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "case_xyz789abc123",
    "type": "technical_report",
    "options": {
      "include_biomechanics": true,
      "use_demo_data": true
    }
  }'

This uses synthetic crash parameters for testing, bypassing the ML inference model.

Error Handling

Always check for errors and handle them appropriately:

async function createReport(caseId) {
  const response = await fetch('/api/reports', {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      case_id: caseId,
      type: 'technical_report',
      options: { include_biomechanics: true }
    })
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(data.error);
  }

  return data.data;
}

Next Steps

• API Reference - Detailed endpoint documentation
• Objects Reference - Object structure details
• Error Handling - Error codes and resolution