# Clinical References

## Create a clinical reference

`auto_scribe.clinical_references.create(ClinicalReferenceCreateParams**kwargs)  -> ClinicalReference`

**post** `/v1/autoScribe/clinicalReferences`

Creates a canonical clinical reference value for study workflow pickers and normalization.

### Parameters

- `name: str`

- `type: ClinicalReferenceType`

  Category of canonical clinical reference value used for study workflow pickers and normalization.

  - `"facility"`

  - `"referring_provider"`

  - `"study_description"`

  - `"procedure"`

- `express_customer_id: Optional[str]`

- `external_reference_id: Optional[str]`

- `metadata: Optional[Dict[str, str]]`

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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
)
clinical_reference = client.auto_scribe.clinical_references.create(
    name="City Medical Center",
    type="facility",
)
print(clinical_reference.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-15T09:00:00Z",
  "isActive": true,
  "name": "City Medical Center",
  "type": "facility",
  "updatedAt": "2024-03-15T14:20:00Z",
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalReferenceId": "FAC-001",
  "metadata": {
    "region": "northeast"
  }
}
```

## List clinical references

`auto_scribe.clinical_references.list(ClinicalReferenceListParams**kwargs)  -> SyncCursorClinicalReferences[ClinicalReference]`

**get** `/v1/autoScribe/clinicalReferences`

Lists clinical references with cursor-based pagination and optional filters.

### Parameters

- `cursor: Optional[str]`

  Base64 encoded cursor from previous response

- `express_customer_id: Optional[str]`

  Filter by Express customer ID. Omit for no filter; pass null for clinic-wide references

- `is_active: Optional[bool]`

  Filter by active status. Defaults to true (active references only). Pass false to list inactive references.

- `limit: Optional[float]`

  Number of results to return (1-100)

- `type: Optional[ClinicalReferenceType]`

  Filter by clinical reference type

  - `"facility"`

  - `"referring_provider"`

  - `"study_description"`

  - `"procedure"`

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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.auto_scribe.clinical_references.list()
page = page.clinical_references[0]
print(page.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferences": [
    {
      "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
      "createdAt": "2024-01-15T09:00:00Z",
      "isActive": true,
      "name": "City Medical Center",
      "type": "facility",
      "updatedAt": "2024-03-15T14:20:00Z",
      "expressCustomer": {
        "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
        "expressCustomerName": "City Medical Center"
      },
      "externalReferenceId": "FAC-001",
      "metadata": {
        "region": "northeast"
      }
    }
  ],
  "hasMore": true,
  "cursor": "cursor"
}
```

## Retrieve a clinical reference by ID

`auto_scribe.clinical_references.retrieve(strclinical_reference_id)  -> ClinicalReference`

**get** `/v1/autoScribe/clinicalReferences/{clinicalReferenceId}`

Retrieves a single clinical reference by its unique identifier.

### Parameters

- `clinical_reference_id: str`

  Unique clinical reference identifier. Format: ref_{32-hex-chars}

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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
)
clinical_reference = client.auto_scribe.clinical_references.retrieve(
    "ref_1234567890abcdef1234567890abcdef",
)
print(clinical_reference.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-15T09:00:00Z",
  "isActive": true,
  "name": "City Medical Center",
  "type": "facility",
  "updatedAt": "2024-03-15T14:20:00Z",
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalReferenceId": "FAC-001",
  "metadata": {
    "region": "northeast"
  }
}
```

## Retrieve a clinical reference by external reference ID

`auto_scribe.clinical_references.retrieve_by_external_reference_id(strexternal_reference_id)  -> ClinicalReference`

**get** `/v1/autoScribe/clinicalReferences/byExternalReferenceId/{externalReferenceId}`

Retrieves a single clinical reference by its integrator-provided external reference identifier.

### Parameters

- `external_reference_id: str`

  Integrator-provided external reference identifier

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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
)
clinical_reference = client.auto_scribe.clinical_references.retrieve_by_external_reference_id(
    "FAC-001",
)
print(clinical_reference.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-15T09:00:00Z",
  "isActive": true,
  "name": "City Medical Center",
  "type": "facility",
  "updatedAt": "2024-03-15T14:20:00Z",
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalReferenceId": "FAC-001",
  "metadata": {
    "region": "northeast"
  }
}
```

## Update a clinical reference

`auto_scribe.clinical_references.update(strclinical_reference_id, ClinicalReferenceUpdateParams**kwargs)  -> ClinicalReference`

**patch** `/v1/autoScribe/clinicalReferences/{clinicalReferenceId}`

Updates name, metadata, and Express customer assignment. Type is immutable after create.

### Parameters

- `clinical_reference_id: str`

  Unique clinical reference identifier. Format: ref_{32-hex-chars}

- `express_customer_id: Optional[str]`

- `metadata: Optional[Dict[str, str]]`

- `name: Optional[str]`

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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
)
clinical_reference = client.auto_scribe.clinical_references.update(
    clinical_reference_id="ref_1234567890abcdef1234567890abcdef",
)
print(clinical_reference.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-15T09:00:00Z",
  "isActive": true,
  "name": "City Medical Center",
  "type": "facility",
  "updatedAt": "2024-03-15T14:20:00Z",
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalReferenceId": "FAC-001",
  "metadata": {
    "region": "northeast"
  }
}
```

## Delete a clinical reference

`auto_scribe.clinical_references.delete(strclinical_reference_id)  -> ClinicalReference`

**post** `/v1/autoScribe/clinicalReferences/{clinicalReferenceId}/delete`

Soft-deletes a clinical reference by setting isActive to false and suffixing the name to free the unique constraint.

### Parameters

- `clinical_reference_id: str`

  Unique clinical reference identifier. Format: ref_{32-hex-chars}

### Returns

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs

### 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
)
clinical_reference = client.auto_scribe.clinical_references.delete(
    "ref_1234567890abcdef1234567890abcdef",
)
print(clinical_reference.clinical_reference_id)
```

#### Response

```json
{
  "clinicalReferenceId": "ref_1234567890abcdef1234567890abcdef",
  "createdAt": "2024-01-15T09:00:00Z",
  "isActive": true,
  "name": "City Medical Center",
  "type": "facility",
  "updatedAt": "2024-03-15T14:20:00Z",
  "expressCustomer": {
    "expressCustomerId": "cus_1234567890abcdef1234567890abcdef",
    "expressCustomerName": "City Medical Center"
  },
  "externalReferenceId": "FAC-001",
  "metadata": {
    "region": "northeast"
  }
}
```

## Domain Types

### Clinical Reference

- `class ClinicalReference: …`

  A canonical clinical reference value for study workflow pickers and normalization

  - `clinical_reference_id: str`

    Unique clinical reference identifier. Format: ref_{32-hex-chars}

  - `created_at: Optional[datetime]`

    Timestamp when the clinical reference was created

  - `is_active: bool`

    Whether this reference is active and available for pickers

  - `name: str`

    Canonical display name for this reference value

  - `type: ClinicalReferenceType`

    Category of canonical clinical reference value used for study workflow pickers and normalization.

    - `"facility"`

    - `"referring_provider"`

    - `"study_description"`

    - `"procedure"`

  - `updated_at: Optional[datetime]`

    Timestamp when the clinical reference was last updated

  - `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

  - `external_reference_id: Optional[str]`

    Integrator-provided stable identifier for mapping inbound data

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata. Maximum 50 pairs