Create an external study

auto_scribe.studies.external.create() -> ExternalCreateResponse

POST/v1/autoScribe/studies/external

Creates an archive (external) AutoScribe study. Clinical context fields are not accepted. If no report fields are sent, no report row is created. Study create is all-or-nothing, including file ingest.

ParametersExpand Collapse

report_metadata: StudyReportMetadataParam

Patient demographics and scan information for report generation

age: Optional[str]

Patient’s age at study date (e.g., ‘34.5 years’, ‘2 months’)

date_of_birth: Optional[str]

Patient’s date of birth. Format: YYYY-MM-DD (e.g., ‘1990-05-20’)

facility_name: Optional[str]

Name of the medical facility where the scan was performed

height: Optional[Height]

Patient’s height with unit (e.g., {value: 70, unit: ‘inches’} or {value: 178, unit: ‘cm’})

unit: HeightUnit

Unit of measure for a height value. ‘in’ = inches, ‘cm’ = centimeters.

One of the following:

"in"

"cm"

value: float

minimum0

mrn: Optional[str]

Medical Record Number - unique patient identifier

patient_name: Optional[str]

Full name of the patient

procedure: Optional[str]

Procedure or study type (e.g., ‘MRI Brain with Contrast’). Maps to database scan_type and dictation report_header.scan_type.

referring_physician_name: Optional[str]

Name of the physician who referred the patient for this scan

sex: Optional[Sex]

Patient’s biological sex. Options: ‘male’, ‘female’, ‘other’

One of the following:

"male"

"female"

"other"

study_date: Optional[str]

Study date (YYYY-MM-DD). Maps to database scan_date and dictation report_header.scan_date.

study_time: Optional[str]

Study time (HH:MM). Maps to database scan_time and dictation report_header.scan_time.

weight: Optional[Weight]

Patient’s weight with unit (e.g., {value: 150, unit: ‘lbs’} or {value: 68, unit: ‘kg’})

unit: WeightUnit

Unit of measure for a weight value. ‘lbs’ = pounds, ‘kg’ = kilograms.

One of the following:

"lbs"

"kg"

value: float

minimum0

severity: Severity

Priority level of a study. ‘normal’ for routine, ‘high’ for urgent, ‘stat’ for immediate attention.

One of the following:

"normal"

"high"

"stat"

study_description: str

Description of the study/scan (e.g., ‘Brain MRI with Contrast’, ‘Chest CT’)

minLength1

study_instance_uid: str

DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., ‘1.2.840.10008.5.1.4.1.1.2’)

minLength1

express_customer_id: Optional[str]

external_patient_id: Optional[str]

Strongly recommended if you want to leverage priors functionality for future reads for this patient.

metadata: Optional[Dict[str, str]]

Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

modality: Optional[str]

reader_name: Optional[str]

Optional original reader / author name. Shown as-is. May be set on study create or a later report create; a later create overwrites it when provided.

minLength1

maxLength256

report_file_name: Optional[str]

File name including extension. Required when reportFileUrl is provided. Supported types: PDF, PNG, JPG, GIF, WEBP.

minLength1

maxLength512

report_file_url: Optional[str]

HTTPS download URL for a PDF or image (PNG, JPG, GIF, WEBP). Not used for AI tooling; the reader can still access it. Avara fetches this URL server-side. If omitted, you can add it later. Once set, it cannot be edited; delete the study to remake it. Whitelist https://api.avarasoftware.com on the file host if the fetch is origin-restricted.

formaturi

report_text: Optional[str]

When this study is used as a prior, report AI tools leverage this text directly. If omitted, you can add it later via POST /studies/external/reports. Once set, it cannot be edited; delete the study to remake it.

minLength1

maxLength50000

signed_at: Optional[str]

Optional original sign-off timestamp or label. Shown as-is with no format validation. May be set on study create or a later report create; a later create overwrites it when provided.

minLength1

maxLength128

ReturnsExpand Collapse

class ExternalCreateResponse: …

A study entity in the AutoScribe system with report workflow status

cancelled_at: Optional[datetime]

Timestamp when the study was cancelled, null if not cancelled

formatdate-time

created_at: Optional[datetime]

Timestamp when the study was created

formatdate-time

is_cancelled: bool

Whether the study has been cancelled

report_metadata: StudyReportMetadata

Patient demographics and scan information for report generation

age: Optional[str]

Patient’s age at study date (e.g., ‘34.5 years’, ‘2 months’)

date_of_birth: Optional[str]

Patient’s date of birth. Format: YYYY-MM-DD (e.g., ‘1990-05-20’)

facility_name: Optional[str]

Name of the medical facility where the scan was performed

height: Optional[Height]

Patient’s height with unit (e.g., {value: 70, unit: ‘inches’} or {value: 178, unit: ‘cm’})

unit: HeightUnit

Unit of measure for a height value. ‘in’ = inches, ‘cm’ = centimeters.

One of the following:

"in"

"cm"

value: float

minimum0

mrn: Optional[str]

Medical Record Number - unique patient identifier

patient_name: Optional[str]

Full name of the patient

procedure: Optional[str]

Procedure or study type (e.g., ‘MRI Brain with Contrast’). Maps to database scan_type and dictation report_header.scan_type.

referring_physician_name: Optional[str]

Name of the physician who referred the patient for this scan

sex: Optional[Sex]

Patient’s biological sex. Options: ‘male’, ‘female’, ‘other’

One of the following:

"male"

"female"

"other"

study_date: Optional[str]

Study date (YYYY-MM-DD). Maps to database scan_date and dictation report_header.scan_date.

study_time: Optional[str]

Study time (HH:MM). Maps to database scan_time and dictation report_header.scan_time.

weight: Optional[Weight]

Patient’s weight with unit (e.g., {value: 150, unit: ‘lbs’} or {value: 68, unit: ‘kg’})

unit: WeightUnit

Unit of measure for a weight value. ‘lbs’ = pounds, ‘kg’ = kilograms.

One of the following:

"lbs"

"kg"

value: float

minimum0

severity: Severity

Priority level of a study. ‘normal’ for routine, ‘high’ for urgent, ‘stat’ for immediate attention.

One of the following:

"normal"

"high"

"stat"

study_description: str

Description of the study/scan (e.g., ‘Brain MRI with Contrast’, ‘Chest CT’)

minLength1

study_id: str

Unique study identifier. Format: stu_{32-hex-chars}

study_instance_uid: str

DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., ‘1.2.840.10008.5.1.4.1.1.2’)

minLength1

study_report_status: StudyReportStatus

AutoScribe report workflow status for a study. ‘unassigned’ = no radiologist assigned, ‘assigned’ = assigned but not started, ‘in_progress’ = actively being dictated, ‘completed’ = report signed, ‘addendum_active’ = addendum in progress.

One of the following:

"unassigned"

"assigned"

"in_progress"

"completed"

"addendum_active"

updated_at: Optional[datetime]

Timestamp when the study was last updated

formatdate-time

assigned_to: Optional[UserReference]

A reference to a user with basic identifying information

email: str

User’s email address

user_id: str

Unique user identifier. Format: usr_{32-hex-chars}

first_name: Optional[str]

User’s first name

last_name: Optional[str]

User’s last name

middle_name: Optional[str]

User’s middle name

suffix1: Optional[str]

Name suffix (e.g., ‘MD’, ‘Jr.’)

suffix2: Optional[str]

Additional name suffix

clinical_history: Optional[str]

Relevant clinical history for the study

clinical_indication: Optional[str]

Clinical indication for the study

created_by_api_key: Optional[APIKeyReference]

A reference to an API key with basic identifying information

api_key_id: str

Unique API key identifier (UUIDv4 format)

formatuuid

description: str

Human-readable description of the API key

minLength1

is_clinical_context_enrichment_enabled: Optional[bool]

Whether this API key has a clinical-context enrichment webhook configured

is_viewer_enabled: Optional[bool]

Whether this API key has access to the Viewer product

created_by_user: Optional[UserReference]

A reference to a user with basic identifying information

email: str

User’s email address

user_id: str

Unique user identifier. Format: usr_{32-hex-chars}

first_name: Optional[str]

User’s first name

last_name: Optional[str]

User’s last name

middle_name: Optional[str]

User’s middle name

suffix1: Optional[str]

Name suffix (e.g., ‘MD’, ‘Jr.’)

suffix2: Optional[str]

Additional name suffix

express_customer: Optional[ExpressCustomerReference]

A reference to an Express customer with basic identifying information

express_customer_id: str

Unique Express customer identifier. Format: cus_{32-hex-chars}

express_customer_name: str

Name of the Express customer

minLength1

external_patient_id: Optional[str]

Integrator-provided stable patient identifier for linking studies

external_report_id: Optional[str]

External report identifier when this study has an attached archive report. Format: ext_{32-hex-chars}

is_critical: Optional[bool]

Whether the primary report was marked as critical at sign-off

metadata: Optional[Dict[str, str]]

Custom key-value metadata for the study. Maximum 50 pairs, keys up to 100 chars, values up to 1000 chars

modality: Optional[str]

Imaging modality for the study (free text)

prior_reports: Optional[List[PriorReport]]

External prior reports with metadata and text

report_text: str

Full prior report text

minLength1

maxLength50000

external_study_id: Optional[str]

Integrator’s external study identifier

minLength1

maxLength256

modality: Optional[str]

Imaging modality for the prior study

minLength1

maxLength100

study_date: Optional[str]

Prior study date (YYYY-MM-DD)

study_description: Optional[str]

Description of the prior study

minLength1

maxLength1000

report_ids: Optional[List[ReportIDWithStatus]]

Array of report IDs associated with this study, including addendums

is_critical: Optional[bool]

Whether the report was marked critical at sign-off. null when the report is not yet completed; true/false once completed.

report_id: str

Unique report identifier. Format: rep_{32-hex-chars}

status: ReportStatus

Status of an individual report. ‘in_progress’ = actively being dictated, ‘completed’ = signed.

One of the following:

"in_progress"

"completed"

study_type: Optional[StudyType]

Kind of study. ‘standard’ is a live AutoScribe reading-workflow study. ‘external’ is an imported archive study.

One of the following:

"standard"

"external"

technologist_notes: Optional[List[str]]

Technologist notes for the study

technologist_technique: Optional[str]

Imaging technique description

Create an external study

import os
from avara import Avara

client = Avara(
    api_key=os.environ.get("AVARA_API_KEY"),  # This is the default and can be omitted
)
external = client.auto_scribe.studies.external.create(
    report_metadata={},
    severity="normal",
    study_description="CT Chest without contrast",
    study_instance_uid="1.2.840.113619.2.55.3.604688119.868.1234567890.123",
)
print(external.study_instance_uid)

{
  "cancelledAt": null,
  "createdAt": "2024-03-15T10:30:00Z",
  "isCancelled": false,
  "reportMetadata": {
    "age": "38 years",
    "dateOfBirth": "1985-07-20",
    "facilityName": "City Medical Center",
    "height": {
      "unit": "cm",
      "value": 165
    },
    "mrn": "MRN-2024-001234",
    "patientName": "Jane Doe",
    "procedure": "MRI Brain with Contrast",
    "referringPhysicianName": "Dr. Michael Chen",
    "sex": "female",
    "studyDate": "2024-03-15",
    "studyTime": "14:30",
    "weight": {
      "unit": "kg",
      "value": 62
    }
  },
  "severity": "normal",
  "studyDescription": "Brain MRI with Contrast",
  "studyId": "stu_1234567890abcdef1234567890abcdef",
  "studyInstanceUid": "1.2.840.113619.2.55.3.604688119.868.1234567890.123",
  "studyReportStatus": "in_progress",
  "updatedAt": "2024-03-15T14:20:00Z",
  "assignedTo": {
    "email": "dr.smith@radiology.com",
    "userId": "usr_1234567890abcdef1234567890abcdef",
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Robert",
    "suffix1": "MD",
    "suffix2": "FACR"
  },
  "clinicalHistory": "clinicalHistory",
  "clinicalIndication": "clinicalIndication",
  "createdByApiKey": {
    "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Production API Key",
    "isClinicalContextEnrichmentEnabled": true,
    "isViewerEnabled": true
  },
  "createdByUser": {
    "email": "dr.smith@radiology.com",
    "userId": "usr_1234567890abcdef1234567890abcdef",
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Robert",
    "suffix1": "MD",
    "suffix2": "FACR"
  },
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalPatientId": "externalPatientId",
  "externalReportId": "ext_1234567890abcdef1234567890abcdef",
  "isCritical": true,
  "metadata": {
    "department": "radiology",
    "priority": "routine"
  },
  "modality": "modality",
  "priorReports": [
    {
      "reportText": "IMPRESSION: No acute cardiopulmonary process.",
      "externalStudyId": "EXT-2024-001",
      "modality": "CT",
      "studyDate": "2024-01-15",
      "studyDescription": "CT Chest without contrast"
    }
  ],
  "reportIds": [
    {
      "isCritical": null,
      "reportId": "rep_1234567890abcdef1234567890abcdef",
      "status": "in_progress"
    }
  ],
  "studyType": "standard",
  "technologistNotes": [
    "x"
  ],
  "technologistTechnique": "technologistTechnique"
}

Returns Examples

{
  "cancelledAt": null,
  "createdAt": "2024-03-15T10:30:00Z",
  "isCancelled": false,
  "reportMetadata": {
    "age": "38 years",
    "dateOfBirth": "1985-07-20",
    "facilityName": "City Medical Center",
    "height": {
      "unit": "cm",
      "value": 165
    },
    "mrn": "MRN-2024-001234",
    "patientName": "Jane Doe",
    "procedure": "MRI Brain with Contrast",
    "referringPhysicianName": "Dr. Michael Chen",
    "sex": "female",
    "studyDate": "2024-03-15",
    "studyTime": "14:30",
    "weight": {
      "unit": "kg",
      "value": 62
    }
  },
  "severity": "normal",
  "studyDescription": "Brain MRI with Contrast",
  "studyId": "stu_1234567890abcdef1234567890abcdef",
  "studyInstanceUid": "1.2.840.113619.2.55.3.604688119.868.1234567890.123",
  "studyReportStatus": "in_progress",
  "updatedAt": "2024-03-15T14:20:00Z",
  "assignedTo": {
    "email": "dr.smith@radiology.com",
    "userId": "usr_1234567890abcdef1234567890abcdef",
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Robert",
    "suffix1": "MD",
    "suffix2": "FACR"
  },
  "clinicalHistory": "clinicalHistory",
  "clinicalIndication": "clinicalIndication",
  "createdByApiKey": {
    "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Production API Key",
    "isClinicalContextEnrichmentEnabled": true,
    "isViewerEnabled": true
  },
  "createdByUser": {
    "email": "dr.smith@radiology.com",
    "userId": "usr_1234567890abcdef1234567890abcdef",
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Robert",
    "suffix1": "MD",
    "suffix2": "FACR"
  },
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalPatientId": "externalPatientId",
  "externalReportId": "ext_1234567890abcdef1234567890abcdef",
  "isCritical": true,
  "metadata": {
    "department": "radiology",
    "priority": "routine"
  },
  "modality": "modality",
  "priorReports": [
    {
      "reportText": "IMPRESSION: No acute cardiopulmonary process.",
      "externalStudyId": "EXT-2024-001",
      "modality": "CT",
      "studyDate": "2024-01-15",
      "studyDescription": "CT Chest without contrast"
    }
  ],
  "reportIds": [
    {
      "isCritical": null,
      "reportId": "rep_1234567890abcdef1234567890abcdef",
      "status": "in_progress"
    }
  ],
  "studyType": "standard",
  "technologistNotes": [
    "x"
  ],
  "technologistTechnique": "technologistTechnique"
}