# Viewer # Studies ## Create `viewer.studies.create(StudyCreateParams**kwargs) -> StudyCreateResponse` **post** `/v1/viewer/studies` Creates a new study in the Viewer system with the specified DICOM Study Instance UID and metadata. The study can be optionally assigned to a user. ### Parameters - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `assigned_to: Optional[str]` User ID to assign the study to. Format: usr_{32-hex-chars} - `express_customer_id: Optional[str]` Express customer ID for the study. Format: cus_{32-hex-chars} - `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 ### Returns - `class StudyCreateResponse: …` A study entity in the Viewer system with viewing status - `cancelled_at: Optional[datetime]` Timestamp when the study was cancelled, null if not cancelled - `created_at: Optional[datetime]` Timestamp when the study was created - `is_cancelled: bool` Whether the study has been cancelled - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `study_viewer_status: Literal["incomplete", "complete"]` - `"incomplete"` - `"complete"` - `updated_at: Optional[datetime]` Timestamp when the study was last updated - `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 - `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) - `description: str` Human-readable description of the API key - `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 - `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 ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) study = client.viewer.studies.create( severity="high", study_description="CT Chest/Abdomen/Pelvis", study_instance_uid="1.2.840.113619.2.55.3.604688119.868.1234567890.123", ) print(study.study_instance_uid) ``` ## List `viewer.studies.list(StudyListParams**kwargs) -> SyncCursorStudies[StudyListResponse]` **get** `/v1/viewer/studies` Retrieves a paginated list of studies with optional filtering by assignment, severity, description, cancellation status, and viewer status. Returns up to 100 studies per request. ### Parameters - `assigned_to: Optional[str]` Filter by assigned user ID (null = explicitly unassigned). Format: usr_<32-hex-chars> - `cursor: Optional[str]` Base64 encoded cursor from previous response - `express_customer_id: Optional[str]` Filter by Express customer ID (null = studies with no customer). Format: cus_{32-hex-chars} - `is_cancelled: Optional[bool]` Filter by cancellation status - `limit: Optional[float]` Number of results to return (1-100) - `severity: Optional[Literal["normal", "high", "stat"]]` Filter by study severity - `"normal"` - `"high"` - `"stat"` - `study_description: Optional[str]` Filter by study description (contains match) - `study_viewer_status: Optional[Literal["incomplete", "complete"]]` Filter by study viewer status - `"incomplete"` - `"complete"` ### Returns - `class StudyListResponse: …` A study entity in the Viewer system with viewing status - `cancelled_at: Optional[datetime]` Timestamp when the study was cancelled, null if not cancelled - `created_at: Optional[datetime]` Timestamp when the study was created - `is_cancelled: bool` Whether the study has been cancelled - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `study_viewer_status: Literal["incomplete", "complete"]` - `"incomplete"` - `"complete"` - `updated_at: Optional[datetime]` Timestamp when the study was last updated - `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 - `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) - `description: str` Human-readable description of the API key - `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 - `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 ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) page = client.viewer.studies.list() page = page.studies[0] print(page.study_instance_uid) ``` ## Retrieve `viewer.studies.retrieve(strstudy_id) -> StudyRetrieveResponse` **get** `/v1/viewer/studies/{studyId}` Retrieves a single study by its unique study ID. Returns the complete study object with all metadata and status information. ### Parameters - `study_id: str` Unique study identifier. Format: stu_{32-hex-chars} ### Returns - `class StudyRetrieveResponse: …` A study entity in the Viewer system with viewing status - `cancelled_at: Optional[datetime]` Timestamp when the study was cancelled, null if not cancelled - `created_at: Optional[datetime]` Timestamp when the study was created - `is_cancelled: bool` Whether the study has been cancelled - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `study_viewer_status: Literal["incomplete", "complete"]` - `"incomplete"` - `"complete"` - `updated_at: Optional[datetime]` Timestamp when the study was last updated - `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 - `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) - `description: str` Human-readable description of the API key - `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 - `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 ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) study = client.viewer.studies.retrieve( "stu_1234567890abcdef1234567890abcdef", ) print(study.study_instance_uid) ``` ## Update `viewer.studies.update(strstudy_id, StudyUpdateParams**kwargs) -> StudyUpdateResponse` **patch** `/v1/viewer/studies/{studyId}` Updates a study's properties including description, severity, assignment, organization, and metadata. All fields are optional - only provided fields will be updated. ### Parameters - `study_id: str` Unique study identifier. Format: stu_{32-hex-chars} - `assigned_to: Optional[str]` User ID to assign the study to, or null to unassign. Format: usr_{32-hex-chars} - `metadata: Optional[Dict[str, str]]` - `severity: Optional[Literal["normal", "high", "stat"]]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: Optional[str]` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `study_viewer_status: Optional[Literal["incomplete", "complete"]]` - `"incomplete"` - `"complete"` ### Returns - `class StudyUpdateResponse: …` A study entity in the Viewer system with viewing status - `cancelled_at: Optional[datetime]` Timestamp when the study was cancelled, null if not cancelled - `created_at: Optional[datetime]` Timestamp when the study was created - `is_cancelled: bool` Whether the study has been cancelled - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `study_viewer_status: Literal["incomplete", "complete"]` - `"incomplete"` - `"complete"` - `updated_at: Optional[datetime]` Timestamp when the study was last updated - `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 - `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) - `description: str` Human-readable description of the API key - `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 - `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 ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) study = client.viewer.studies.update( study_id="stu_1234567890abcdef1234567890abcdef", ) print(study.study_instance_uid) ``` ## Cancel `viewer.studies.cancel(StudyCancelParams**kwargs) -> StudyCancelResponse` **post** `/v1/viewer/studies/cancel` Marks a study as cancelled. Cancelled studies are preserved but flagged as inactive. Can be identified by either study ID or DICOM Study Instance UID. ### Parameters - `study_id: Optional[str]` Unique study identifier. Format: stu_{32-hex-chars} - `study_instance_uid: Optional[str]` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `class StudyCancelResponse: …` Response for cancelling a study in Viewer - `success: bool` - `message: Optional[str]` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.studies.cancel() print(response.success) ``` ## Uncancel `viewer.studies.uncancel(StudyUncancelParams**kwargs) -> StudyUncancelResponse` **post** `/v1/viewer/studies/uncancel` Restores a cancelled study to active status. The study must have been previously cancelled. Can be identified by either study ID or DICOM Study Instance UID. ### Parameters - `study_id: Optional[str]` Unique study identifier. Format: stu_{32-hex-chars} - `study_instance_uid: Optional[str]` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `class StudyUncancelResponse: …` Response for uncancelling a study in Viewer - `success: bool` - `message: Optional[str]` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.studies.uncancel() print(response.success) ``` ## Reroute URL `viewer.studies.reroute_url(StudyRerouteURLParams**kwargs) -> StudyRerouteURLResponse` **post** `/v1/viewer/studies/reroute-url` Generates a tokenized URL that redirects users directly to the Avara Viewer for the specified study. The URL includes authentication and is time-limited for security. ### Parameters - `study_id: Optional[str]` Unique study identifier. Format: stu_{32-hex-chars} - `study_instance_uid: Optional[str]` DICOM Study Instance UID. Must be a valid DICOM UID format (e.g., '1.2.840.10008.5.1.4.1.1.2') ### Returns - `class StudyRerouteURLResponse: …` Response containing the generated reroute URL for a study in Viewer - `url: str` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.studies.reroute_url() print(response.url) ``` ## Retrieve By Uid `viewer.studies.retrieve_by_uid(strstudy_instance_uid) -> StudyRetrieveByUidResponse` **get** `/v1/viewer/studies/by-uid/{studyInstanceUid}` Retrieves a single study by its DICOM Study Instance UID. This is useful when you have the DICOM UID but not the Avara study ID. ### Parameters - `study_instance_uid: str` DICOM Study Instance UID. Format: numbers and dots (e.g., 1.2.840.10008.5.1.4.1.1.2). ### Returns - `class StudyRetrieveByUidResponse: …` A study entity in the Viewer system with viewing status - `cancelled_at: Optional[datetime]` Timestamp when the study was cancelled, null if not cancelled - `created_at: Optional[datetime]` Timestamp when the study was created - `is_cancelled: bool` Whether the study has been cancelled - `severity: Literal["normal", "high", "stat"]` Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention - `"normal"` - `"high"` - `"stat"` - `study_description: str` Description of the study/scan (e.g., 'Brain MRI with Contrast', 'Chest CT') - `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') - `study_viewer_status: Literal["incomplete", "complete"]` - `"incomplete"` - `"complete"` - `updated_at: Optional[datetime]` Timestamp when the study was last updated - `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 - `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) - `description: str` Human-readable description of the API key - `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 - `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 ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.studies.retrieve_by_uid( "1.2.840.10008.5.1.4.1.1.2", ) print(response.study_instance_uid) ``` # Users ## Invite `viewer.users.invite(UserInviteParams**kwargs) -> UserInviteResponse` **post** `/v1/viewer/users` Creates a new user in the Viewer system and sends them an invitation email. The user will have the specified permissions and access level. Dashboard access can be enabled to allow login. ### Parameters - `can_manage_studies: bool` - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` User's clinical or organizational role - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `email: str` User's email address for login and notifications - `first_name: str` User's first name - `has_dashboard_access: bool` - `last_name: str` User's last name - `level: Literal["admin", "member"]` - `"admin"` - `"member"` - `middle_name: Optional[str]` User's middle name (optional) - `phone_number: Optional[str]` User's phone number (10-15 digits, optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional - `suffix2: Optional[str]` Additional name suffix (optional) ### Returns - `class UserInviteResponse: …` Response for inviting a user to Viewer. Level is restricted to admin/member since owners cannot be invited via API. - `can_manage_studies: bool` Whether the user has permission to create, update, and manage studies - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` User's clinical or organizational role - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the user was created - `email: str` User's email address for login and notifications - `first_name: str` User's first name - `has_dashboard_access: bool` Whether the user can access the dashboard interface. Required for admin users - `invited_source: Literal["dashboard", "api"]` How the user was invited - via dashboard UI or API - `"dashboard"` - `"api"` - `last_login_at: Optional[datetime]` Timestamp of user's last login, null if never logged in - `last_name: str` User's last name - `level: Literal["admin", "member"]` User access level. 'admin' can manage users/settings, 'member' has standard access - `"admin"` - `"member"` - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} - `middle_name: Optional[str]` User's middle name (optional) - `phone_number: Optional[str]` User's phone number (10-15 digits, optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional - `suffix2: Optional[str]` Additional name suffix (optional) ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.users.invite( can_manage_studies=True, clinic_role="Radiologist", email="dr.johnson@hospital.org", first_name="Sarah", has_dashboard_access=True, last_name="Johnson", level="member", ) print(response.middle_name) ``` ## List `viewer.users.list(UserListParams**kwargs) -> SyncCursorUsers[UserListResponse]` **get** `/v1/viewer/users` Retrieves a paginated list of users with optional filtering by access level, email, name, and invitation source. Returns up to 100 users per request. ### Parameters - `cursor: Optional[str]` Base64 encoded cursor from previous response - `email: Optional[str]` Filter by exact email match - `first_name: Optional[str]` Filter by first name (contains match) - `invited_source: Optional[Literal["dashboard", "api"]]` Filter by invitation source - `"dashboard"` - `"api"` - `last_name: Optional[str]` Filter by last name (contains match) - `level: Optional[Literal["owner", "admin", "member"]]` Filter by user level - `"owner"` - `"admin"` - `"member"` - `limit: Optional[float]` Number of results to return (1-100) ### Returns - `class UserListResponse: …` A user in the Viewer system with study management permissions - `can_manage_studies: bool` Whether the user has permission to create, update, and manage studies - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` User's clinical or organizational role - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the user was created - `email: str` User's email address for login and notifications - `first_name: str` User's first name - `has_dashboard_access: bool` Whether the user can access the dashboard interface. Required for admin users - `invited_source: Literal["dashboard", "api"]` How the user was invited - via dashboard UI or API - `"dashboard"` - `"api"` - `last_login_at: Optional[datetime]` Timestamp of user's last login, null if never logged in - `last_name: str` User's last name - `level: Literal["owner", "admin", "member"]` User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access - `"owner"` - `"admin"` - `"member"` - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} - `middle_name: Optional[str]` User's middle name (optional) - `phone_number: Optional[str]` User's phone number (10-15 digits, optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional - `suffix2: Optional[str]` Additional name suffix (optional) ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) page = client.viewer.users.list() page = page.users[0] print(page.middle_name) ``` ## Retrieve `viewer.users.retrieve(struser_id) -> UserRetrieveResponse` **get** `/v1/viewer/users/{userId}` Retrieves a single user by their unique user ID. Returns the complete user object with all profile information, permissions, and status. ### Parameters - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} ### Returns - `class UserRetrieveResponse: …` A user in the Viewer system with study management permissions - `can_manage_studies: bool` Whether the user has permission to create, update, and manage studies - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` User's clinical or organizational role - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the user was created - `email: str` User's email address for login and notifications - `first_name: str` User's first name - `has_dashboard_access: bool` Whether the user can access the dashboard interface. Required for admin users - `invited_source: Literal["dashboard", "api"]` How the user was invited - via dashboard UI or API - `"dashboard"` - `"api"` - `last_login_at: Optional[datetime]` Timestamp of user's last login, null if never logged in - `last_name: str` User's last name - `level: Literal["owner", "admin", "member"]` User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access - `"owner"` - `"admin"` - `"member"` - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} - `middle_name: Optional[str]` User's middle name (optional) - `phone_number: Optional[str]` User's phone number (10-15 digits, optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional - `suffix2: Optional[str]` Additional name suffix (optional) ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) user = client.viewer.users.retrieve( "usr_1234567890abcdef1234567890abcdef", ) print(user.middle_name) ``` ## Update `viewer.users.update(struser_id, UserUpdateParams**kwargs) -> UserUpdateResponse` **patch** `/v1/viewer/users/{userId}` Updates a user's profile information, permissions, and access level. All fields are optional - only provided fields will be updated. Email cannot be changed via API. ### Parameters - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} - `can_manage_studies: Optional[bool]` - `clinic_role: Optional[Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]]` - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `first_name: Optional[str]` User's first name - `has_dashboard_access: Optional[bool]` Whether the user can access the dashboard interface. Required for admin users - `last_name: Optional[str]` User's last name - `level: Optional[Literal["admin", "member"]]` - `"admin"` - `"member"` - `middle_name: Optional[str]` - `phone_number: Optional[str]` - `suffix1: Optional[str]` - `suffix2: Optional[str]` ### Returns - `class UserUpdateResponse: …` A user in the Viewer system with study management permissions - `can_manage_studies: bool` Whether the user has permission to create, update, and manage studies - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` User's clinical or organizational role - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the user was created - `email: str` User's email address for login and notifications - `first_name: str` User's first name - `has_dashboard_access: bool` Whether the user can access the dashboard interface. Required for admin users - `invited_source: Literal["dashboard", "api"]` How the user was invited - via dashboard UI or API - `"dashboard"` - `"api"` - `last_login_at: Optional[datetime]` Timestamp of user's last login, null if never logged in - `last_name: str` User's last name - `level: Literal["owner", "admin", "member"]` User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access - `"owner"` - `"admin"` - `"member"` - `user_id: str` Unique user identifier. Format: usr_{32-hex-chars} - `middle_name: Optional[str]` User's middle name (optional) - `phone_number: Optional[str]` User's phone number (10-15 digits, optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional - `suffix2: Optional[str]` Additional name suffix (optional) ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) user = client.viewer.users.update( user_id="usr_1234567890abcdef1234567890abcdef", ) print(user.middle_name) ``` ## Revoke Access `viewer.users.revoke_access(UserRevokeAccessParams**kwargs) -> UserRevokeAccessResponse` **post** `/v1/viewer/users/revoke-access` Deactivates a user's access to the system. The user will no longer be able to log in or access resources. User data is preserved and can be reactivated later. ### Parameters - `user_id: str` User ID to revoke access for. Format: usr_{32-hex-chars} ### Returns - `class UserRevokeAccessResponse: …` Response for revoking user access in Viewer - `success: bool` - `message: Optional[str]` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.users.revoke_access( user_id="usr_1234567890abcdef1234567890abcdef", ) print(response.success) ``` ## Reactivate `viewer.users.reactivate(UserReactivateParams**kwargs) -> UserReactivateResponse` **post** `/v1/viewer/users/reactivate` Restores access for a previously deactivated user. The user will regain their original permissions and be able to log in again. ### Parameters - `user_id: str` User ID to reactivate. Format: usr_{32-hex-chars} ### Returns - `class UserReactivateResponse: …` Response for reactivating a user in Viewer - `success: bool` - `message: Optional[str]` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.users.reactivate( user_id="usr_1234567890abcdef1234567890abcdef", ) print(response.success) ``` # Invitations ## List `viewer.users.invitations.list(InvitationListParams**kwargs) -> SyncCursorInvitations[InvitationListResponse]` **get** `/v1/viewer/users/invitations` Retrieves a paginated list of user invitations with optional filtering by status, expiration, date range, and user ID. Returns up to 100 invitations per request. ### Parameters - `cursor: Optional[str]` Base64 encoded cursor from previous response - `end_date: Optional[str]` Filter invitations created on or before this date (YYYY-MM-DD) - `expired: Optional[Literal["all", "expired", "not-expired"]]` Filter by expiration status - `"all"` - `"expired"` - `"not-expired"` - `limit: Optional[float]` Number of results to return (1-100) - `start_date: Optional[str]` Filter invitations created on or after this date (YYYY-MM-DD) - `status: Optional[List[Literal["sent", "accepted", "rejected", "revoked"]]]` Filter by invitation status(es) - `"sent"` - `"accepted"` - `"rejected"` - `"revoked"` - `user_id: Optional[str]` Filter by user ID. Format: usr_{32-hex-chars} ### Returns - `class InvitationListResponse: …` A pending user invitation in the Viewer system - `can_manage_studies: bool` Whether the invited user will have permission to manage studies - `clinic_id: str` UUID of the clinic this invitation belongs to - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` Clinical or organizational role for the invited user - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the invitation was created - `email: str` Email address the invitation was sent to - `expiry: Optional[datetime]` When the invitation expires, null if no expiration - `first_name: str` Invited user's first name - `has_dashboard_access: bool` Whether the invited user will have dashboard access - `invitation_id: str` Unique invitation identifier. Format: inv_{32-hex-chars} - `invited_source: Literal["dashboard", "api"]` How the invitation was created - 'dashboard' or 'api' - `"dashboard"` - `"api"` - `inviter_id: str` User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API - `last_name: str` Invited user's last name - `level: Literal["owner", "admin", "member"]` Access level for the invited user. 'admin' or 'member' when created via API - `"owner"` - `"admin"` - `"member"` - `status: Literal["sent", "accepted", "rejected", "revoked"]` Invitation status: 'sent', 'accepted', 'rejected', or 'revoked' - `"sent"` - `"accepted"` - `"rejected"` - `"revoked"` - `updated_at: Optional[datetime]` Timestamp when the invitation was last updated - `user_id: str` Pre-generated user ID for this invitation. Format: usr_{32-hex-chars}. This ID is assigned at invitation creation and will become the user's permanent ID upon acceptance - `invited_by_api_key_id: Optional[str]` UUID of the API key used to send this invitation. Null if sent via dashboard - `middle_name: Optional[str]` Invited user's middle name (optional) - `phone_number: Optional[str]` Invited user's phone number (optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'MD') - optional - `suffix2: Optional[str]` Additional name suffix - optional ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) page = client.viewer.users.invitations.list() page = page.invitations[0] print(page.middle_name) ``` ## Retrieve `viewer.users.invitations.retrieve(strinvitation_id) -> InvitationRetrieveResponse` **get** `/v1/viewer/users/invitations/{invitationId}` Retrieves a single invitation by its unique invitation ID. Returns the complete invitation details including status, expiration, and associated user information. ### Parameters - `invitation_id: str` Unique invitation identifier. Format: inv_{32-hex-chars} ### Returns - `class InvitationRetrieveResponse: …` A pending user invitation in the Viewer system - `can_manage_studies: bool` Whether the invited user will have permission to manage studies - `clinic_id: str` UUID of the clinic this invitation belongs to - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` Clinical or organizational role for the invited user - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the invitation was created - `email: str` Email address the invitation was sent to - `expiry: Optional[datetime]` When the invitation expires, null if no expiration - `first_name: str` Invited user's first name - `has_dashboard_access: bool` Whether the invited user will have dashboard access - `invitation_id: str` Unique invitation identifier. Format: inv_{32-hex-chars} - `invited_source: Literal["dashboard", "api"]` How the invitation was created - 'dashboard' or 'api' - `"dashboard"` - `"api"` - `inviter_id: str` User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API - `last_name: str` Invited user's last name - `level: Literal["owner", "admin", "member"]` Access level for the invited user. 'admin' or 'member' when created via API - `"owner"` - `"admin"` - `"member"` - `status: Literal["sent", "accepted", "rejected", "revoked"]` Invitation status: 'sent', 'accepted', 'rejected', or 'revoked' - `"sent"` - `"accepted"` - `"rejected"` - `"revoked"` - `updated_at: Optional[datetime]` Timestamp when the invitation was last updated - `user_id: str` Pre-generated user ID for this invitation. Format: usr_{32-hex-chars}. This ID is assigned at invitation creation and will become the user's permanent ID upon acceptance - `invited_by_api_key_id: Optional[str]` UUID of the API key used to send this invitation. Null if sent via dashboard - `middle_name: Optional[str]` Invited user's middle name (optional) - `phone_number: Optional[str]` Invited user's phone number (optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'MD') - optional - `suffix2: Optional[str]` Additional name suffix - optional ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) invitation = client.viewer.users.invitations.retrieve( "inv_1234567890abcdef1234567890abcdef", ) print(invitation.middle_name) ``` ## Update `viewer.users.invitations.update(strinvitation_id, InvitationUpdateParams**kwargs) -> InvitationUpdateResponse` **patch** `/v1/viewer/users/invitations/{invitationId}` Updates a pending invitation's user details and permissions before it is accepted. Only valid for invitations that have not expired or been processed. ### Parameters - `invitation_id: str` Unique invitation identifier. Format: inv_{32-hex-chars} - `can_manage_studies: Optional[bool]` - `clinic_role: Optional[Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]]` - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `first_name: Optional[str]` Invited user's first name - `has_dashboard_access: Optional[bool]` Whether the invited user will have dashboard access - `last_name: Optional[str]` Invited user's last name - `level: Optional[Literal["admin", "member"]]` - `"admin"` - `"member"` - `middle_name: Optional[str]` - `phone_number: Optional[str]` - `suffix1: Optional[str]` - `suffix2: Optional[str]` ### Returns - `class InvitationUpdateResponse: …` A pending user invitation in the Viewer system - `can_manage_studies: bool` Whether the invited user will have permission to manage studies - `clinic_id: str` UUID of the clinic this invitation belongs to - `clinic_role: Literal["Radiologist", "Cardiologist", "Neurologist", 18 more]` Clinical or organizational role for the invited user - `"Radiologist"` - `"Cardiologist"` - `"Neurologist"` - `"Urologist"` - `"Gynecologist"` - `"Endocrinologist"` - `"Doctor"` - `"Surgeon"` - `"Physician"` - `"Physician Assistant"` - `"Nurse Practitioner"` - `"Registered Nurse"` - `"Patient Care Coordinator"` - `"Front Desk Operator"` - `"Imaging Technologist"` - `"PACS Administrator"` - `"Software Engineer"` - `"Revenue Cycle Manager"` - `"Administrative Director"` - `"Administrative Assistant"` - `"Other"` - `created_at: Optional[datetime]` Timestamp when the invitation was created - `email: str` Email address the invitation was sent to - `expiry: Optional[datetime]` When the invitation expires, null if no expiration - `first_name: str` Invited user's first name - `has_dashboard_access: bool` Whether the invited user will have dashboard access - `invitation_id: str` Unique invitation identifier. Format: inv_{32-hex-chars} - `invited_source: Literal["dashboard", "api"]` How the invitation was created - 'dashboard' or 'api' - `"dashboard"` - `"api"` - `inviter_id: str` User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API - `last_name: str` Invited user's last name - `level: Literal["owner", "admin", "member"]` Access level for the invited user. 'admin' or 'member' when created via API - `"owner"` - `"admin"` - `"member"` - `status: Literal["sent", "accepted", "rejected", "revoked"]` Invitation status: 'sent', 'accepted', 'rejected', or 'revoked' - `"sent"` - `"accepted"` - `"rejected"` - `"revoked"` - `updated_at: Optional[datetime]` Timestamp when the invitation was last updated - `user_id: str` Pre-generated user ID for this invitation. Format: usr_{32-hex-chars}. This ID is assigned at invitation creation and will become the user's permanent ID upon acceptance - `invited_by_api_key_id: Optional[str]` UUID of the API key used to send this invitation. Null if sent via dashboard - `middle_name: Optional[str]` Invited user's middle name (optional) - `phone_number: Optional[str]` Invited user's phone number (optional) - `suffix1: Optional[str]` Name suffix (e.g., 'Jr.', 'MD') - optional - `suffix2: Optional[str]` Additional name suffix - optional ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) invitation = client.viewer.users.invitations.update( invitation_id="inv_1234567890abcdef1234567890abcdef", ) print(invitation.middle_name) ``` ## Revoke `viewer.users.invitations.revoke(InvitationRevokeParams**kwargs) -> InvitationRevokeResponse` **post** `/v1/viewer/users/invitations/revoke` Revokes a pending invitation, preventing it from being accepted. Can revoke by invitation ID, user ID, or both. Useful for cancelling invitations sent in error. ### Parameters - `invitation_id: Optional[str]` Invitation ID to revoke. Format: inv_{32-hex-chars} - `user_id: Optional[str]` User ID whose pending invitation to revoke. Format: usr_{32-hex-chars} ### Returns - `class InvitationRevokeResponse: …` Response for revoking an invitation in Viewer - `success: bool` - `message: Optional[str]` ### Example ```python import os from avara import Avara client = Avara( api_key=os.environ.get("AVARA_API_KEY"), # This is the default and can be omitted ) response = client.viewer.users.invitations.revoke() print(response.success) ```