API Data Model

Introduction

The Avara API provides separate SDK packages (or delineations) for each product — AutoScribe and Viewer. Each product has its own set of objects, endpoints, and data structures optimized for its specific use case. This guide explains the core objects, branded identifiers, and key attributes for each product.

SDK Packages

Avara provides separate SDK packages for each product:

• avara.autoScribe — SDK for AutoScribe operations (studies, reports, users with report creation permissions)
• avara.viewer — SDK for Viewer operations (studies, users with study management permissions)

While both products share some common concepts (like studies and users), they have distinct object types and attributes tailored to their workflows.

Branded Identifiers

All Avara resources use branded identifiers with consistent prefixes:

Identifier Type	Format	Example	Description
StudyId	stu_{32-hex-chars}	stu_1234567890abcdef1234567890abcdef	Unique study identifier
UserId	usr_{32-hex-chars}	usr_1234567890abcdef1234567890abcdef	Unique user identifier
ReportId	rep_{32-hex-chars}	rep_1234567890abcdef1234567890abcdef	Unique report identifier (AutoScribe only)
InvitationId	inv_{32-hex-chars}	inv_1234567890abcdef1234567890abcdef	Unique invitation identifier
ExpressCustomerId	cus_{32-hex-chars}	cus_1234567890abcdef1234567890abcdef	Unique Express customer identifier

All identifiers use a 3-character prefix followed by 32 hexadecimal characters (64 total characters including prefix).

AutoScribe Objects

AutoScribeStudy

Represents a study in the AutoScribe system with report workflow status.

Key Attributes:

• studyId (StudyId, required) — Unique study identifier
• studyInstanceUid (string, required) — DICOM Study Instance UID (e.g., 1.2.840.113619.2.55.3.604688119.868.1234567890.123)
• studyDescription (string, required) — Description of the study/scan (e.g., “Brain MRI with Contrast”)
• severity (enum, required) — Priority level: "normal", "high", or "stat"
• studyReportStatus (enum, required) — Report workflow status:
  • "unassigned" — No radiologist assigned
  • "assigned" — Assigned but not started
  • "in_progress" — Actively being dictated
  • "completed" — Report signed
  • "addendum_active" — Addendum in progress
• reportIds (array of ReportIdWithStatus) — Array of report IDs associated with this study, including addendums
• reportMetadata (StudyReportMetadata, required) — Patient demographics and scan information for report generation
• assignedTo (UserReference, nullable) — Reference to the assigned radiologist, null if unassigned
• priorStudyIds (array of strings) — Array of prior study IDs for comparison context
• priorReportTexts (array of strings) — Array of prior report texts to provide clinical context
• metadata (object, optional) — Custom key-value metadata (max 50 pairs, keys up to 100 chars, values up to 1000 chars)
• isCancelled (boolean, required) — Whether the study has been cancelled
• cancelledAt (datetime, nullable) — Timestamp when the study was cancelled
• createdAt (datetime, nullable) — Timestamp when the study was created
• updatedAt (datetime, nullable) — Timestamp when the study was last updated

AutoScribeUser

Represents a user in the AutoScribe system with report creation permissions.

Key Attributes:

• userId (UserId, required) — Unique user identifier
• email (string, required) — User’s email address for login and notifications
• firstName (string, required) — User’s first name
• lastName (string, required) — User’s last name
• middleName (string, optional) — User’s middle name
• suffix1 (string, optional) — Name suffix (e.g., “MD”, “Jr.”)
• suffix2 (string, optional) — Additional name suffix (e.g., “FACR”)
• clinicRole (enum, required) — Clinical or organizational role (e.g., “Radiologist”, “Cardiologist”, “Doctor”)
• phoneNumber (string, optional) — User’s phone number (10-15 digits)
• level (enum, required) — Access level: "owner", "admin", or "member"
• hasDashboardAccess (boolean, required) — Whether the user can access the dashboard interface
• canManageStudies (boolean, required) — Whether the user has permission to create, update, and manage studies
• canCreateReports (boolean, required) — Whether the user can generate and sign radiology reports
• npiNumber (string, optional) — National Provider Identifier (10-digit number, required for users who can create reports)
• invitedSource (enum, required) — How the user was invited: "dashboard" or "api"
• lastLoginAt (datetime, nullable) — Timestamp of user’s last login
• createdAt (datetime, nullable) — Timestamp when the user was created

AutoScribeReport

Represents a radiology report in the AutoScribe system.

Key Attributes:

• reportId (ReportId, required) — Unique report identifier
• studyId (StudyId, required) — Study ID this report belongs to
• status (enum, required) — Report status: "in_progress" or "completed"
• reportPlainText (string) — Plain text content of the report
• snapshotMetadata (StudyReportMetadata, required) — Patient demographics and scan information frozen at report creation time
• isAddendum (boolean, required) — Whether this report is an addendum to a previous report
• userId (UserId, required) — User ID of the radiologist who created/signed this report
• signedAt (datetime, nullable) — Timestamp when the report was signed
• createdAt (datetime, nullable) — Timestamp when the report was created
• updatedAt (datetime, nullable) — Timestamp when the report was last updated

AutoScribeInvitation

Represents a pending user invitation in the AutoScribe system.

Key Attributes:

• invitationId (InvitationId, required) — Unique invitation identifier
• userId (UserId, required) — Pre-generated user ID for this invitation (becomes permanent upon acceptance)
• email (string, required) — Email address the invitation was sent to
• firstName (string, required) — Invited user’s first name
• lastName (string, required) — Invited user’s last name
• clinicRole (enum, required) — Clinical or organizational role
• level (enum, required) — Access level: "admin" or "member" (owners cannot be invited via API)
• hasDashboardAccess (boolean, required) — Whether the invited user will have dashboard access
• canManageStudies (boolean, required) — Whether the invited user will have permission to manage studies
• canCreateReports (boolean, required) — Whether the invited user can generate and sign radiology reports
• npiNumber (string, optional) — National Provider Identifier (required if canCreateReports is true)
• status (enum, required) — Invitation status: "sent", "accepted", "rejected", or "revoked"
• expiry (datetime, nullable) — When the invitation expires
• invitedSource (enum, required) — How the invitation was created: "dashboard" or "api"
• createdAt (datetime, nullable) — Timestamp when the invitation was created
• updatedAt (datetime, nullable) — Timestamp when the invitation was last updated

Viewer Objects

ViewerStudy

Represents a study in the Viewer system with viewing status.

Key Attributes:

• studyId (StudyId, required) — Unique study identifier
• studyInstanceUid (string, required) — DICOM Study Instance UID
• studyDescription (string, required) — Description of the study/scan
• severity (enum, required) — Priority level: "normal", "high", or "stat"
• studyViewerStatus (enum, required) — Viewer status: "incomplete" or "complete"
• assignedTo (UserReference, nullable) — Reference to the assigned user, null if unassigned
• expressCustomer (ExpressCustomerReference, nullable) — Reference to the Express customer this study belongs to
• metadata (object, optional) — Custom key-value metadata (max 50 pairs)
• isCancelled (boolean, required) — Whether the study has been cancelled
• cancelledAt (datetime, nullable) — Timestamp when the study was cancelled
• createdAt (datetime, nullable) — Timestamp when the study was created
• updatedAt (datetime, nullable) — Timestamp when the study was last updated

Note: Viewer studies do not include reportMetadata, reportIds, priorStudyIds, or priorReportTexts since Viewer focuses on image viewing rather than report generation.

ViewerUser

Represents a user in the Viewer system with study management permissions.

Key Attributes:

• userId (UserId, required) — Unique user identifier
• email (string, required) — User’s email address for login and notifications
• firstName (string, required) — User’s first name
• lastName (string, required) — User’s last name
• middleName (string, optional) — User’s middle name
• suffix1 (string, optional) — Name suffix
• suffix2 (string, optional) — Additional name suffix
• clinicRole (enum, required) — Clinical or organizational role
• phoneNumber (string, optional) — User’s phone number
• level (enum, required) — Access level: "owner", "admin", or "member"
• hasDashboardAccess (boolean, required) — Whether the user can access the dashboard interface
• canManageStudies (boolean, required) — Whether the user has permission to create, update, and manage studies
• invitedSource (enum, required) — How the user was invited: "dashboard" or "api"
• lastLoginAt (datetime, nullable) — Timestamp of user’s last login
• createdAt (datetime, nullable) — Timestamp when the user was created

Note: Viewer users do not include canCreateReports or npiNumber since Viewer does not support report creation.

ViewerInvitation

Represents a pending user invitation in the Viewer system.

Key Attributes:

• invitationId (InvitationId, required) — Unique invitation identifier
• userId (UserId, required) — Pre-generated user ID for this invitation
• email (string, required) — Email address the invitation was sent to
• firstName (string, required) — Invited user’s first name
• lastName (string, required) — Invited user’s last name
• clinicRole (enum, required) — Clinical or organizational role
• level (enum, required) — Access level: "admin" or "member"
• hasDashboardAccess (boolean, required) — Whether the invited user will have dashboard access
• canManageStudies (boolean, required) — Whether the invited user will have permission to manage studies
• status (enum, required) — Invitation status: "sent", "accepted", "rejected", or "revoked"
• expiry (datetime, nullable) — When the invitation expires
• invitedSource (enum, required) — How the invitation was created: "dashboard" or "api"
• createdAt (datetime, nullable) — Timestamp when the invitation was created
• updatedAt (datetime, nullable) — Timestamp when the invitation was last updated

Note: Viewer invitations do not include canCreateReports or npiNumber since Viewer does not support report creation.

Shared Objects

UserReference

A reference to a user with basic identifying information. Used in both AutoScribe and Viewer contexts.

Key Attributes:

• userId (UserId, required) — Unique user identifier
• email (string, required) — User’s email address
• firstName (string, optional) — User’s first name
• lastName (string, optional) — User’s last name
• middleName (string, optional) — User’s middle name
• suffix1 (string, optional) — Name suffix
• suffix2 (string, optional) — Additional name suffix

ExpressCustomerReference

A reference to an Express customer with basic identifying information.

Key Attributes:

• expressCustomerId (ExpressCustomerId, required) — Unique Express customer identifier
• expressCustomerName (string, required) — Name of the Express customer

ApiKeyReference

A reference to an API key with basic identifying information.

Key Attributes:

• apiKeyId (UUID, required) — Unique API key identifier (UUIDv4 format)
• description (string, required) — Human-readable description of the API key
• isViewerEnabled (boolean, optional) — Whether this API key has access to the Viewer product

StudyReportMetadata

Patient demographics and scan information for report generation. Used in AutoScribe studies and reports.

Key Attributes:

• scanDate (string, required) — Date the scan was performed (format: YYYY-MM-DD)
• scanType (string, optional) — Type of scan or imaging modality (e.g., “MRI”, “CT”, “X-Ray”)
• patientName (string, optional) — Full name of the patient
• facilityName (string, optional) — Name of the medical facility where the scan was performed
• referringPhysicianName (string, optional) — Name of the physician who referred the patient
• sex (enum, optional) — Patient’s biological sex: "male", "female", or "other"
• height (object, optional) — Patient’s height with unit (value and unit: "in" or "cm")
• weight (object, optional) — Patient’s weight with unit (value and unit: "lbs" or "kg")
• dateOfBirth (string, optional) — Patient’s date of birth (format: YYYY-MM-DD)
• mrn (string, optional) — Medical Record Number — unique patient identifier
• scanTime (string, optional) — Time the scan was performed (format: HH:MM)
• age (string, optional) — Patient’s age at time of scan (e.g., “34.5 years”, “2 months”)

ReportIdWithStatus

A report ID paired with its current status. Used in AutoScribe studies.

Key Attributes:

• reportId (ReportId, required) — Unique report identifier
• status (enum, required) — Current status of the report: "in_progress" or "completed"

Express Customer Objects

ExpressCustomer

An Express customer entity that groups users and studies.

Key Attributes:

• expressCustomerId (ExpressCustomerId, required) — Unique Express customer identifier
• expressCustomerName (string, required) — Name of the Express customer
• isActive (boolean, required) — Whether the Express customer is currently active
• metadata (object, optional) — Custom key-value metadata (max 50 pairs)
• userCount (integer, required) — Number of users currently in this Express customer
• createdAt (datetime, nullable) — Timestamp when the Express customer was created
• updatedAt (datetime, nullable) — Timestamp when the Express customer was last updated

Key Differences Between Products

AutoScribe vs Viewer Studies

Attribute	AutoScribeStudy	ViewerStudy
Report workflow status	studyReportStatus (unassigned, assigned, in_progress, completed, addendum_active)	N/A
Viewer status	N/A	studyViewerStatus (incomplete, complete)
Report metadata	reportMetadata (required)	N/A
Report IDs	reportIds (array)	N/A
Prior studies/reports	priorStudyIds, priorReportTexts	N/A

AutoScribe vs Viewer Users

Attribute	AutoScribeUser	ViewerUser
Report creation	canCreateReports (boolean)	N/A
NPI number	npiNumber (string, required if canCreateReports)	N/A
Study management	canManageStudies (boolean)	canManageStudies (boolean)

SDK Usage Examples

TypeScript

import Avara from '@avara/sdk';

const avara = new Avara({ apiKey: process.env.AVARA_API_KEY });

// AutoScribe SDK
const autoScribeStudy = await avara.autoScribe.studies.create({
  studyInstanceUid: '1.2.840.113619.2.55.3.604688119.868.1234567890.123',
  studyDescription: 'Brain MRI with Contrast',
  severity: 'normal',
  reportMetadata: {
    scanDate: '2024-03-15',
    scanType: 'MRI Brain with Contrast',
    patientName: 'Jane Doe',
    facilityName: 'City Medical Center',
    sex: 'female',
    dateOfBirth: '1985-07-20',
    mrn: 'MRN-2024-001234',
  },
});

// Viewer SDK
const viewerStudy = await avara.viewer.studies.create({
  studyInstanceUid: '1.2.840.113619.2.55.3.604688119.868.1234567890.123',
  studyDescription: 'CT Chest/Abdomen/Pelvis',
  severity: 'high',
});

Python

from avara import Avara

avara = Avara(api_key=os.environ['AVARA_API_KEY'])

# AutoScribe SDK
auto_scribe_study = avara.auto_scribe.studies.create(
    study_instance_uid='1.2.840.113619.2.55.3.604688119.868.1234567890.123',
    study_description='Brain MRI with Contrast',
    severity='normal',
    report_metadata={
        'scan_date': '2024-03-15',
        'scan_type': 'MRI Brain with Contrast',
        'patient_name': 'Jane Doe',
        'facility_name': 'City Medical Center',
        'sex': 'female',
        'date_of_birth': '1985-07-20',
        'mrn': 'MRN-2024-001234',
    },
)

# Viewer SDK
viewer_study = avara.viewer.studies.create(
    study_instance_uid='1.2.840.113619.2.55.3.604688119.868.1234567890.123',
    study_description='CT Chest/Abdomen/Pelvis',
    severity='high',
)

Java

import com.avara.Avara;
import com.avara.models.autoscribe.*;
import com.avara.models.viewer.*;

Avara avara = new Avara.Builder()
    .apiKey(System.getenv("AVARA_API_KEY"))
    .build();

// AutoScribe SDK
AutoScribeStudyCreateRequest autoScribeRequest = AutoScribeStudyCreateRequest.builder()
    .studyInstanceUid("1.2.840.113619.2.55.3.604688119.868.1234567890.123")
    .studyDescription("Brain MRI with Contrast")
    .severity(Severity.NORMAL)
    .reportMetadata(StudyReportMetadata.builder()
        .scanDate("2024-03-15")
        .scanType("MRI Brain with Contrast")
        .patientName("Jane Doe")
        .facilityName("City Medical Center")
        .sex(Sex.FEMALE)
        .dateOfBirth("1985-07-20")
        .mrn("MRN-2024-001234")
        .build())
    .build();

AutoScribeStudy autoScribeStudy = avara.autoScribe().studies().create(autoScribeRequest);

// Viewer SDK
ViewerStudyCreateRequest viewerRequest = ViewerStudyCreateRequest.builder()
    .studyInstanceUid("1.2.840.113619.2.55.3.604688119.868.1234567890.123")
    .studyDescription("CT Chest/Abdomen/Pelvis")
    .severity(Severity.HIGH)
    .build();

ViewerStudy viewerStudy = avara.viewer().studies().create(viewerRequest);

Summary

• AutoScribe focuses on report generation with objects like AutoScribeStudy, AutoScribeUser, AutoScribeReport, and AutoScribeInvitation. Users can create reports and require NPI numbers.

• Viewer focuses on image viewing with objects like ViewerStudy, ViewerUser, and ViewerInvitation. Users manage studies but do not create reports.

• Both products share common concepts (studies, users, invitations) but have distinct attributes and workflows optimized for their specific use cases.

• All resources use branded identifiers with consistent prefixes (stu_, usr_, rep_, inv_, cus_) followed by 32 hexadecimal characters.