# Viewer

# Studies

## Create

**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.

### Body Parameters

- `severity: "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: string`

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

- `studyInstanceUid: string`

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

- `assignedTo: optional string`

  User ID to assign the study to. Format: usr_{32-hex-chars}

- `expressCustomerId: optional string`

  Express customer ID for the study. Format: cus_{32-hex-chars}

- `metadata: optional map[string]`

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

### Returns

- `cancelledAt: string`

  Timestamp when the study was cancelled, null if not cancelled

- `createdAt: string`

  Timestamp when the study was created

- `isCancelled: boolean`

  Whether the study has been cancelled

- `severity: "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: string`

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

- `studyId: string`

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

- `studyInstanceUid: string`

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

- `studyViewerStatus: "incomplete" or "complete"`

  - `"incomplete"`

  - `"complete"`

- `updatedAt: string`

  Timestamp when the study was last updated

- `assignedTo: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `createdByApiKey: optional APIKeyReference`

  A reference to an API key with basic identifying information

  - `apiKeyId: string`

    Unique API key identifier (UUIDv4 format)

  - `description: string`

    Human-readable description of the API key

  - `isViewerEnabled: optional boolean`

    Whether this API key has access to the Viewer product

- `createdByUser: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `expressCustomer: optional ExpressCustomerReference`

  A reference to an Express customer with basic identifying information

  - `expressCustomerId: string`

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

  - `expressCustomerName: string`

    Name of the Express customer

- `metadata: optional map[string]`

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

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AVARA_API_KEY" \
    -d '{
          "severity": "high",
          "studyDescription": "CT Chest/Abdomen/Pelvis",
          "studyInstanceUid": "1.2.840.113619.2.55.3.604688119.868.1234567890.123",
          "assignedTo": "usr_1234567890abcdef1234567890abcdef",
          "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
          "metadata": {
            "department": "radiology",
            "priority": "urgent"
          }
        }'
```

## List

**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.

### Query Parameters

- `assignedTo: optional string`

  Filter by assigned user ID (null = explicitly unassigned). Format: usr_<32-hex-chars>

- `cursor: optional string`

  Base64 encoded cursor from previous response

- `expressCustomerId: optional string`

  Filter by Express customer ID (null = studies with no customer). Format: cus_{32-hex-chars}

- `isCancelled: optional boolean`

  Filter by cancellation status

- `limit: optional number`

  Number of results to return (1-100)

- `severity: optional "normal" or "high" or "stat"`

  Filter by study severity

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: optional string`

  Filter by study description (contains match)

- `studyViewerStatus: optional "incomplete" or "complete"`

  Filter by study viewer status

  - `"incomplete"`

  - `"complete"`

### Returns

- `hasMore: boolean`

- `studies: array of object { cancelledAt, createdAt, isCancelled, 11 more }`

  - `cancelledAt: string`

    Timestamp when the study was cancelled, null if not cancelled

  - `createdAt: string`

    Timestamp when the study was created

  - `isCancelled: boolean`

    Whether the study has been cancelled

  - `severity: "normal" or "high" or "stat"`

    Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

    - `"normal"`

    - `"high"`

    - `"stat"`

  - `studyDescription: string`

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

  - `studyId: string`

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

  - `studyInstanceUid: string`

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

  - `studyViewerStatus: "incomplete" or "complete"`

    - `"incomplete"`

    - `"complete"`

  - `updatedAt: string`

    Timestamp when the study was last updated

  - `assignedTo: optional UserReference`

    A reference to a user with basic identifying information

    - `email: string`

      User's email address

    - `userId: string`

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

    - `firstName: optional string`

      User's first name

    - `lastName: optional string`

      User's last name

    - `middleName: optional string`

      User's middle name

    - `suffix1: optional string`

      Name suffix (e.g., 'MD', 'Jr.')

    - `suffix2: optional string`

      Additional name suffix

  - `createdByApiKey: optional APIKeyReference`

    A reference to an API key with basic identifying information

    - `apiKeyId: string`

      Unique API key identifier (UUIDv4 format)

    - `description: string`

      Human-readable description of the API key

    - `isViewerEnabled: optional boolean`

      Whether this API key has access to the Viewer product

  - `createdByUser: optional UserReference`

    A reference to a user with basic identifying information

    - `email: string`

      User's email address

    - `userId: string`

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

    - `firstName: optional string`

      User's first name

    - `lastName: optional string`

      User's last name

    - `middleName: optional string`

      User's middle name

    - `suffix1: optional string`

      Name suffix (e.g., 'MD', 'Jr.')

    - `suffix2: optional string`

      Additional name suffix

  - `expressCustomer: optional ExpressCustomerReference`

    A reference to an Express customer with basic identifying information

    - `expressCustomerId: string`

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

    - `expressCustomerName: string`

      Name of the Express customer

  - `metadata: optional map[string]`

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

- `cursor: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Retrieve

**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.

### Path Parameters

- `studyId: string`

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

### Returns

- `cancelledAt: string`

  Timestamp when the study was cancelled, null if not cancelled

- `createdAt: string`

  Timestamp when the study was created

- `isCancelled: boolean`

  Whether the study has been cancelled

- `severity: "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: string`

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

- `studyId: string`

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

- `studyInstanceUid: string`

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

- `studyViewerStatus: "incomplete" or "complete"`

  - `"incomplete"`

  - `"complete"`

- `updatedAt: string`

  Timestamp when the study was last updated

- `assignedTo: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `createdByApiKey: optional APIKeyReference`

  A reference to an API key with basic identifying information

  - `apiKeyId: string`

    Unique API key identifier (UUIDv4 format)

  - `description: string`

    Human-readable description of the API key

  - `isViewerEnabled: optional boolean`

    Whether this API key has access to the Viewer product

- `createdByUser: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `expressCustomer: optional ExpressCustomerReference`

  A reference to an Express customer with basic identifying information

  - `expressCustomerId: string`

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

  - `expressCustomerName: string`

    Name of the Express customer

- `metadata: optional map[string]`

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

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/$STUDY_ID \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Update

**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.

### Path Parameters

- `studyId: string`

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

### Body Parameters

- `assignedTo: optional string`

  User ID to assign the study to, or null to unassign. Format: usr_{32-hex-chars}

- `metadata: optional map[string]`

- `severity: optional "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: optional string`

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

- `studyViewerStatus: optional "incomplete" or "complete"`

  - `"incomplete"`

  - `"complete"`

### Returns

- `cancelledAt: string`

  Timestamp when the study was cancelled, null if not cancelled

- `createdAt: string`

  Timestamp when the study was created

- `isCancelled: boolean`

  Whether the study has been cancelled

- `severity: "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: string`

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

- `studyId: string`

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

- `studyInstanceUid: string`

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

- `studyViewerStatus: "incomplete" or "complete"`

  - `"incomplete"`

  - `"complete"`

- `updatedAt: string`

  Timestamp when the study was last updated

- `assignedTo: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `createdByApiKey: optional APIKeyReference`

  A reference to an API key with basic identifying information

  - `apiKeyId: string`

    Unique API key identifier (UUIDv4 format)

  - `description: string`

    Human-readable description of the API key

  - `isViewerEnabled: optional boolean`

    Whether this API key has access to the Viewer product

- `createdByUser: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `expressCustomer: optional ExpressCustomerReference`

  A reference to an Express customer with basic identifying information

  - `expressCustomerId: string`

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

  - `expressCustomerName: string`

    Name of the Express customer

- `metadata: optional map[string]`

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

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/$STUDY_ID \
    -X PATCH \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Cancel

**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.

### Body Parameters

- `studyId: optional string`

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

- `studyInstanceUid: optional string`

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

### Returns

- `success: boolean`

- `message: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/cancel \
    -X POST \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Uncancel

**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.

### Body Parameters

- `studyId: optional string`

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

- `studyInstanceUid: optional string`

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

### Returns

- `success: boolean`

- `message: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/uncancel \
    -X POST \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Reroute URL

**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.

### Body Parameters

- `studyId: optional string`

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

- `studyInstanceUid: optional string`

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

### Returns

- `url: string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/reroute-url \
    -X POST \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Retrieve By Uid

**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.

### Path Parameters

- `studyInstanceUid: string`

  DICOM Study Instance UID. Format: numbers and dots (e.g., 1.2.840.10008.5.1.4.1.1.2).

### Returns

- `cancelledAt: string`

  Timestamp when the study was cancelled, null if not cancelled

- `createdAt: string`

  Timestamp when the study was created

- `isCancelled: boolean`

  Whether the study has been cancelled

- `severity: "normal" or "high" or "stat"`

  Priority level of the study. 'normal' for routine, 'high' for urgent, 'stat' for immediate attention

  - `"normal"`

  - `"high"`

  - `"stat"`

- `studyDescription: string`

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

- `studyId: string`

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

- `studyInstanceUid: string`

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

- `studyViewerStatus: "incomplete" or "complete"`

  - `"incomplete"`

  - `"complete"`

- `updatedAt: string`

  Timestamp when the study was last updated

- `assignedTo: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `createdByApiKey: optional APIKeyReference`

  A reference to an API key with basic identifying information

  - `apiKeyId: string`

    Unique API key identifier (UUIDv4 format)

  - `description: string`

    Human-readable description of the API key

  - `isViewerEnabled: optional boolean`

    Whether this API key has access to the Viewer product

- `createdByUser: optional UserReference`

  A reference to a user with basic identifying information

  - `email: string`

    User's email address

  - `userId: string`

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

  - `firstName: optional string`

    User's first name

  - `lastName: optional string`

    User's last name

  - `middleName: optional string`

    User's middle name

  - `suffix1: optional string`

    Name suffix (e.g., 'MD', 'Jr.')

  - `suffix2: optional string`

    Additional name suffix

- `expressCustomer: optional ExpressCustomerReference`

  A reference to an Express customer with basic identifying information

  - `expressCustomerId: string`

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

  - `expressCustomerName: string`

    Name of the Express customer

- `metadata: optional map[string]`

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

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/studies/by-uid/$STUDY_INSTANCE_UID \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

# Users

## Invite

**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.

### Body Parameters

- `canManageStudies: boolean`

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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: string`

  User's email address for login and notifications

- `firstName: string`

  User's first name

- `hasDashboardAccess: boolean`

- `lastName: string`

  User's last name

- `level: "admin" or "member"`

  - `"admin"`

  - `"member"`

- `middleName: optional string`

  User's middle name (optional)

- `phoneNumber: optional string`

  User's phone number (10-15 digits, optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional

- `suffix2: optional string`

  Additional name suffix (optional)

### Returns

- `canManageStudies: boolean`

  Whether the user has permission to create, update, and manage studies

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `createdAt: string`

  Timestamp when the user was created

- `email: string`

  User's email address for login and notifications

- `firstName: string`

  User's first name

- `hasDashboardAccess: boolean`

  Whether the user can access the dashboard interface. Required for admin users

- `invitedSource: "dashboard" or "api"`

  How the user was invited - via dashboard UI or API

  - `"dashboard"`

  - `"api"`

- `lastLoginAt: string`

  Timestamp of user's last login, null if never logged in

- `lastName: string`

  User's last name

- `level: "admin" or "member"`

  User access level. 'admin' can manage users/settings, 'member' has standard access

  - `"admin"`

  - `"member"`

- `userId: string`

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

- `middleName: optional string`

  User's middle name (optional)

- `phoneNumber: optional string`

  User's phone number (10-15 digits, optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional

- `suffix2: optional string`

  Additional name suffix (optional)

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AVARA_API_KEY" \
    -d '{
          "canManageStudies": true,
          "clinicRole": "Radiologist",
          "email": "dr.johnson@hospital.org",
          "firstName": "Sarah",
          "hasDashboardAccess": true,
          "lastName": "Johnson",
          "level": "member",
          "middleName": "Marie",
          "phoneNumber": "5551234567",
          "suffix1": "MD",
          "suffix2": "FACR"
        }'
```

## List

**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.

### Query Parameters

- `cursor: optional string`

  Base64 encoded cursor from previous response

- `email: optional string`

  Filter by exact email match

- `firstName: optional string`

  Filter by first name (contains match)

- `invitedSource: optional "dashboard" or "api"`

  Filter by invitation source

  - `"dashboard"`

  - `"api"`

- `lastName: optional string`

  Filter by last name (contains match)

- `level: optional "owner" or "admin" or "member"`

  Filter by user level

  - `"owner"`

  - `"admin"`

  - `"member"`

- `limit: optional number`

  Number of results to return (1-100)

### Returns

- `hasMore: boolean`

- `users: array of object { canManageStudies, clinicRole, createdAt, 12 more }`

  - `canManageStudies: boolean`

    Whether the user has permission to create, update, and manage studies

  - `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

  - `createdAt: string`

    Timestamp when the user was created

  - `email: string`

    User's email address for login and notifications

  - `firstName: string`

    User's first name

  - `hasDashboardAccess: boolean`

    Whether the user can access the dashboard interface. Required for admin users

  - `invitedSource: "dashboard" or "api"`

    How the user was invited - via dashboard UI or API

    - `"dashboard"`

    - `"api"`

  - `lastLoginAt: string`

    Timestamp of user's last login, null if never logged in

  - `lastName: string`

    User's last name

  - `level: "owner" or "admin" or "member"`

    User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access

    - `"owner"`

    - `"admin"`

    - `"member"`

  - `userId: string`

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

  - `middleName: optional string`

    User's middle name (optional)

  - `phoneNumber: optional string`

    User's phone number (10-15 digits, optional)

  - `suffix1: optional string`

    Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional

  - `suffix2: optional string`

    Additional name suffix (optional)

- `cursor: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Retrieve

**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.

### Path Parameters

- `userId: string`

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

### Returns

- `canManageStudies: boolean`

  Whether the user has permission to create, update, and manage studies

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `createdAt: string`

  Timestamp when the user was created

- `email: string`

  User's email address for login and notifications

- `firstName: string`

  User's first name

- `hasDashboardAccess: boolean`

  Whether the user can access the dashboard interface. Required for admin users

- `invitedSource: "dashboard" or "api"`

  How the user was invited - via dashboard UI or API

  - `"dashboard"`

  - `"api"`

- `lastLoginAt: string`

  Timestamp of user's last login, null if never logged in

- `lastName: string`

  User's last name

- `level: "owner" or "admin" or "member"`

  User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access

  - `"owner"`

  - `"admin"`

  - `"member"`

- `userId: string`

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

- `middleName: optional string`

  User's middle name (optional)

- `phoneNumber: optional string`

  User's phone number (10-15 digits, optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional

- `suffix2: optional string`

  Additional name suffix (optional)

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/$USER_ID \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Update

**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.

### Path Parameters

- `userId: string`

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

### Body Parameters

- `canManageStudies: optional boolean`

- `clinicRole: optional "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `firstName: optional string`

  User's first name

- `hasDashboardAccess: optional boolean`

  Whether the user can access the dashboard interface. Required for admin users

- `lastName: optional string`

  User's last name

- `level: optional "admin" or "member"`

  - `"admin"`

  - `"member"`

- `middleName: optional string`

- `phoneNumber: optional string`

- `suffix1: optional string`

- `suffix2: optional string`

### Returns

- `canManageStudies: boolean`

  Whether the user has permission to create, update, and manage studies

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `createdAt: string`

  Timestamp when the user was created

- `email: string`

  User's email address for login and notifications

- `firstName: string`

  User's first name

- `hasDashboardAccess: boolean`

  Whether the user can access the dashboard interface. Required for admin users

- `invitedSource: "dashboard" or "api"`

  How the user was invited - via dashboard UI or API

  - `"dashboard"`

  - `"api"`

- `lastLoginAt: string`

  Timestamp of user's last login, null if never logged in

- `lastName: string`

  User's last name

- `level: "owner" or "admin" or "member"`

  User access level. 'owner' has full control, 'admin' can manage users/settings, 'member' has standard access

  - `"owner"`

  - `"admin"`

  - `"member"`

- `userId: string`

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

- `middleName: optional string`

  User's middle name (optional)

- `phoneNumber: optional string`

  User's phone number (10-15 digits, optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'Sr.', 'III') - optional

- `suffix2: optional string`

  Additional name suffix (optional)

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/$USER_ID \
    -X PATCH \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Revoke Access

**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.

### Body Parameters

- `userId: string`

  User ID to revoke access for. Format: usr_{32-hex-chars}

### Returns

- `success: boolean`

- `message: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/revoke-access \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AVARA_API_KEY" \
    -d '{
          "userId": "usr_1234567890abcdef1234567890abcdef"
        }'
```

## Reactivate

**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.

### Body Parameters

- `userId: string`

  User ID to reactivate. Format: usr_{32-hex-chars}

### Returns

- `success: boolean`

- `message: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/reactivate \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AVARA_API_KEY" \
    -d '{
          "userId": "usr_1234567890abcdef1234567890abcdef"
        }'
```

# Invitations

## List

**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.

### Query Parameters

- `cursor: optional string`

  Base64 encoded cursor from previous response

- `endDate: optional string`

  Filter invitations created on or before this date (YYYY-MM-DD)

- `expired: optional "all" or "expired" or "not-expired"`

  Filter by expiration status

  - `"all"`

  - `"expired"`

  - `"not-expired"`

- `limit: optional number`

  Number of results to return (1-100)

- `startDate: optional string`

  Filter invitations created on or after this date (YYYY-MM-DD)

- `status: optional array of "sent" or "accepted" or "rejected" or "revoked"`

  Filter by invitation status(es)

  - `"sent"`

  - `"accepted"`

  - `"rejected"`

  - `"revoked"`

- `userId: optional string`

  Filter by user ID. Format: usr_{32-hex-chars}

### Returns

- `hasMore: boolean`

- `invitations: array of object { canManageStudies, clinicId, clinicRole, 18 more }`

  - `canManageStudies: boolean`

    Whether the invited user will have permission to manage studies

  - `clinicId: string`

    UUID of the clinic this invitation belongs to

  - `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

  - `createdAt: string`

    Timestamp when the invitation was created

  - `email: string`

    Email address the invitation was sent to

  - `expiry: string`

    When the invitation expires, null if no expiration

  - `firstName: string`

    Invited user's first name

  - `hasDashboardAccess: boolean`

    Whether the invited user will have dashboard access

  - `invitationId: string`

    Unique invitation identifier. Format: inv_{32-hex-chars}

  - `invitedSource: "dashboard" or "api"`

    How the invitation was created - 'dashboard' or 'api'

    - `"dashboard"`

    - `"api"`

  - `inviterId: string`

    User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API

  - `lastName: string`

    Invited user's last name

  - `level: "owner" or "admin" or "member"`

    Access level for the invited user. 'admin' or 'member' when created via API

    - `"owner"`

    - `"admin"`

    - `"member"`

  - `status: "sent" or "accepted" or "rejected" or "revoked"`

    Invitation status: 'sent', 'accepted', 'rejected', or 'revoked'

    - `"sent"`

    - `"accepted"`

    - `"rejected"`

    - `"revoked"`

  - `updatedAt: string`

    Timestamp when the invitation was last updated

  - `userId: string`

    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

  - `invitedByApiKeyId: optional string`

    UUID of the API key used to send this invitation. Null if sent via dashboard

  - `middleName: optional string`

    Invited user's middle name (optional)

  - `phoneNumber: optional string`

    Invited user's phone number (optional)

  - `suffix1: optional string`

    Name suffix (e.g., 'Jr.', 'MD') - optional

  - `suffix2: optional string`

    Additional name suffix - optional

- `cursor: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/invitations \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Retrieve

**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.

### Path Parameters

- `invitationId: string`

  Unique invitation identifier. Format: inv_{32-hex-chars}

### Returns

- `canManageStudies: boolean`

  Whether the invited user will have permission to manage studies

- `clinicId: string`

  UUID of the clinic this invitation belongs to

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `createdAt: string`

  Timestamp when the invitation was created

- `email: string`

  Email address the invitation was sent to

- `expiry: string`

  When the invitation expires, null if no expiration

- `firstName: string`

  Invited user's first name

- `hasDashboardAccess: boolean`

  Whether the invited user will have dashboard access

- `invitationId: string`

  Unique invitation identifier. Format: inv_{32-hex-chars}

- `invitedSource: "dashboard" or "api"`

  How the invitation was created - 'dashboard' or 'api'

  - `"dashboard"`

  - `"api"`

- `inviterId: string`

  User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API

- `lastName: string`

  Invited user's last name

- `level: "owner" or "admin" or "member"`

  Access level for the invited user. 'admin' or 'member' when created via API

  - `"owner"`

  - `"admin"`

  - `"member"`

- `status: "sent" or "accepted" or "rejected" or "revoked"`

  Invitation status: 'sent', 'accepted', 'rejected', or 'revoked'

  - `"sent"`

  - `"accepted"`

  - `"rejected"`

  - `"revoked"`

- `updatedAt: string`

  Timestamp when the invitation was last updated

- `userId: string`

  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

- `invitedByApiKeyId: optional string`

  UUID of the API key used to send this invitation. Null if sent via dashboard

- `middleName: optional string`

  Invited user's middle name (optional)

- `phoneNumber: optional string`

  Invited user's phone number (optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'MD') - optional

- `suffix2: optional string`

  Additional name suffix - optional

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/invitations/$INVITATION_ID \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Update

**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.

### Path Parameters

- `invitationId: string`

  Unique invitation identifier. Format: inv_{32-hex-chars}

### Body Parameters

- `canManageStudies: optional boolean`

- `clinicRole: optional "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `firstName: optional string`

  Invited user's first name

- `hasDashboardAccess: optional boolean`

  Whether the invited user will have dashboard access

- `lastName: optional string`

  Invited user's last name

- `level: optional "admin" or "member"`

  - `"admin"`

  - `"member"`

- `middleName: optional string`

- `phoneNumber: optional string`

- `suffix1: optional string`

- `suffix2: optional string`

### Returns

- `canManageStudies: boolean`

  Whether the invited user will have permission to manage studies

- `clinicId: string`

  UUID of the clinic this invitation belongs to

- `clinicRole: "Radiologist" or "Cardiologist" or "Neurologist" or 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"`

- `createdAt: string`

  Timestamp when the invitation was created

- `email: string`

  Email address the invitation was sent to

- `expiry: string`

  When the invitation expires, null if no expiration

- `firstName: string`

  Invited user's first name

- `hasDashboardAccess: boolean`

  Whether the invited user will have dashboard access

- `invitationId: string`

  Unique invitation identifier. Format: inv_{32-hex-chars}

- `invitedSource: "dashboard" or "api"`

  How the invitation was created - 'dashboard' or 'api'

  - `"dashboard"`

  - `"api"`

- `inviterId: string`

  User ID of the person who sent the invitation. Format: usr_{32-hex-chars}. Null if invited via API

- `lastName: string`

  Invited user's last name

- `level: "owner" or "admin" or "member"`

  Access level for the invited user. 'admin' or 'member' when created via API

  - `"owner"`

  - `"admin"`

  - `"member"`

- `status: "sent" or "accepted" or "rejected" or "revoked"`

  Invitation status: 'sent', 'accepted', 'rejected', or 'revoked'

  - `"sent"`

  - `"accepted"`

  - `"rejected"`

  - `"revoked"`

- `updatedAt: string`

  Timestamp when the invitation was last updated

- `userId: string`

  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

- `invitedByApiKeyId: optional string`

  UUID of the API key used to send this invitation. Null if sent via dashboard

- `middleName: optional string`

  Invited user's middle name (optional)

- `phoneNumber: optional string`

  Invited user's phone number (optional)

- `suffix1: optional string`

  Name suffix (e.g., 'Jr.', 'MD') - optional

- `suffix2: optional string`

  Additional name suffix - optional

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/invitations/$INVITATION_ID \
    -X PATCH \
    -H "Authorization: Bearer $AVARA_API_KEY"
```

## Revoke

**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.

### Body Parameters

- `invitationId: optional string`

  Invitation ID to revoke. Format: inv_{32-hex-chars}

- `userId: optional string`

  User ID whose pending invitation to revoke. Format: usr_{32-hex-chars}

### Returns

- `success: boolean`

- `message: optional string`

### Example

```http
curl https://api.avarasoftware.com/v1/viewer/users/invitations/revoke \
    -X POST \
    -H "Authorization: Bearer $AVARA_API_KEY"
```