Create Case

Creates a new case in your account. You can include vehicles, occupants, and accident information in a single request.

POST /api/cases

Request Body

{
  "name": "string",
  "plaintiff_name": "string",
  "defendant_name": "string",
  "attorney_name": "string",
  "side": "plaintiff | defense",
  "analysis_type": "accident_only | accident_injury | delta_v_only | biomechanics_only",
  "organization_id": "string",
  "user_email": "string",

  "accident": {
    "description": "string",
    "date": "YYYY-MM-DD",
    "time": "HH:MM",
    "location": "string"
  },

  "vehicles": [
    {
      "role": "plaintiff | defendant",
      "vehicle_maker": "string",
      "vehicle_model": "string",
      "vehicle_year": "string",
      "vehicle_vin": "string",
      "vehicle_type": "string",
      "airbag_deployed": "yes | no | partial | unknown",
      "deployed_airbags": ["string"],
      "edr_file_id": "string",
      "image_file_ids": ["string"]
    }
  ],

  "occupants": [
    {
      "name": "string",
      "age": 0,
      "gender": "male | female | other",
      "height_inches": 0,
      "weight_lbs": 0,
      "position": "driver | front_passenger | rear_left | rear_center | rear_right",
      "alleged_injuries": ["string"],
      "seatbelt_worn": true,
      "airbag_deployed": "yes | no | partial | unknown",
      "pre_existing_conditions": "string"
    }
  ]
}

Parameters

Required Fields

• plaintiff_name string, required Plaintiff name (injured party). Used for auto-generating case name if not provided.

• defendant_name string, required Defendant name (at-fault party). Used for auto-generating case name if not provided.

• attorney_name string, required Attorney name handling the case

Optional Fields

• name string, optional Case name or title. If not provided, auto-generated as "PlaintiffLastName v. DefendantLastName" (e.g., "Smith v. Johnson")

• side string, optional Which party the attorney represents. One of: plaintiff or defense. Defaults to plaintiff.

• analysis_type string, optional Type of analysis to run on this case. Defaults to accident_only.

  Value	Description	Requires Occupants?
  accident_only	Crash analysis only (default)	No
  accident_injury	Crash analysis + biomechanics	Yes
  delta_v_only	Delta-V calculation only	No
  biomechanics_only	Biomechanics analysis only	Yes

  See Analysis Types Guide for detailed usage and examples.

• organization_id string, optional Organization ID to associate the case with

• user_email string, optional Email of a team member in your account to link this case to. The email must belong to an existing user in the same account. If not provided, the case is linked to the authenticated user (web app) or has no user association (API key). Case-insensitive.

Accident Information

• accident object, optional Accident information

  • accident.description string - Narrative description of the accident
  • accident.date string - Date of accident in YYYY-MM-DD format
  • accident.time string - Time of accident in HH:MM format
  • accident.location string - Location where the accident occurred

Vehicles

• vehicles array of objects, optional List of vehicles involved in the accident

  • vehicles[].role string, required - Vehicle role: plaintiff or defendant
  • vehicles[].vehicle_maker string - Manufacturer (e.g., "Toyota")
  • vehicles[].vehicle_model string - Model (e.g., "Camry")
  • vehicles[].vehicle_year string - Year (e.g., "2020")
  • vehicles[].vehicle_vin string - Vehicle Identification Number
  • vehicles[].vehicle_type string - Type: sedan, suv, truck, motorcycle, etc.
  • vehicles[].airbag_deployed string - Vehicle-level summary status: yes, no, partial, or unknown. If omitted, the API infers yes from any deployed_airbags codes (unless an existing record is partial).
  • vehicles[].deployed_airbags array of strings - Optional detail codes for the specific airbags that deployed. Existing integrations can omit this field and continue using only airbag_deployed. If this field is provided with one or more values and airbag_deployed is omitted, the API stores airbag_deployed as yes. If airbag_deployed is no or unknown, this is stored as an empty array. See Vehicle Airbag Deployment for allowed values.
  • vehicles[].edr_file_id string - File ID of uploaded EDR data
  • vehicles[].image_file_ids array of strings - File IDs of uploaded damage photos

Occupants

• occupants array of objects, optional List of vehicle occupants for biomechanics analysis. Required for accident_injury analysis type — report creation will return 422 (occupants_missing) if no occupants exist.

  When provided, each occupant must include all required fields or the request returns 400 (occupant_field_required).

  Required fields:

  • occupants[].name string, required - Occupant's full name
  • occupants[].age integer, required - Age in years (must be > 0)
  • occupants[].gender string, required - One of: male, female
  • occupants[].height_inches integer, required - Height in inches (must be > 0)
  • occupants[].weight_lbs integer, required - Weight in pounds (must be > 0)
  • occupants[].position string, required - Seating position: driver, front_passenger, rear_left, rear_center, rear_right
  • occupants[].seatbelt_worn boolean, required - Whether seatbelt was worn

  Optional fields:

  • occupants[].alleged_injuries array of strings - Injury types: head_brain, cervical_spine, thoracic_spine, lumbar_spine, shoulder, hip, knee, foot_ankle
  • occupants[].airbag_deployed string - One of: yes, no, partial, unknown
  • occupants[].pre_existing_conditions string - Description of pre-existing medical conditions

Response

{
  "success": true,
  "data": {
    "case": {
      "id": "case_abc123def456",
      "name": "Smith v. Johnson",
      "plaintiff_name": "John Smith",
      "defendant_name": "Mike Johnson",
      "attorney_name": "Jane Attorney",
      "side": "plaintiff",
      "analysis_type": "accident_only",
      "has_edr": false,
      "account_id": "acc_xyz789",
      "organization_id": "org_abc123",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "invoice": {
      "id": "inv_xyz789",
      "amount": 299.00,
      "status": "pending"
    }
  }
}

Examples

Basic case creation (auto-generated name)

Create a case with just the required fields. The case name will be auto-generated as "Smith v. Johnson":

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": "Mike Johnson",
    "attorney_name": "Jane Attorney"
  }'

Basic case creation (custom name)

Create a case with a custom name:

curl -X POST "https://api.silentwitness.ai/api/cases" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smith v. Johnson - Car Accident 2024",
    "plaintiff_name": "John Smith",
    "defendant_name": "Mike Johnson",
    "attorney_name": "Jane Attorney"
  }'

Create case linked to a team member (API key)

When using an API key, you can optionally link the case to a specific team member by providing their email:

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": "Mike Johnson",
    "attorney_name": "Jane Attorney",
    "user_email": "jane@lawfirm.com"
  }'

If user_email is omitted, the case is created at the account level without a specific user association.

Full case with all data

Create a case with vehicles, occupants, and accident information in a single request. The case name will be auto-generated as "Smith v. Johnson":

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": "Mike Johnson",
    "attorney_name": "Jane Attorney",
    "organization_id": "org_abc123",

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

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

    "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"]
      }
    ]
  }'

Errors

Code	Description
400	Invalid request body - missing required fields or invalid enum values
400	user_email not found in this account
401	Unauthorized - Invalid or missing API key
500	Internal server error

Error Examples

Missing required field:

{
  "success": false,
  "error": "plaintiff_name is required",
  "error_code": "bad_request",
  "error_type": "invalid_request_error",
  "request_id": "req_..."
}

Invalid enum value:

{
  "success": false,
  "error": "Invalid analysis_type: invalid_value. Must be one of: accident_only, accident_injury, delta_v_only, biomechanics_only",
  "error_code": "bad_request",
  "error_type": "invalid_request_error",
  "request_id": "req_..."
}

Recommended Workflow

After creating a case with all data:

1. POST /api/cases              → Create case with vehicles, occupants, accident info
2. POST /api/files/upload       → Upload plaintiff damage photos
3. PUT /api/cases/:id           → Link file IDs to plaintiff vehicle
4. POST /api/reports            → Create report (auto-triggers delta-v calculation)
5. GET /api/reports/:id         → Poll for completion

See Update Case for linking uploaded file IDs. See Create Report and Get Report for the Stripe-style reports API.