# Assemble

```
Assemble creates a unique patient graph from a patient's EHR for use in precision CDS
```

{% stepper %}
{% step %}

### Submit a FHIR bundle to create a patient graph

Request body needs to be a FHIR bundle JSON (<https://hl7.org/fhir/R4/bundle.html>)
{% endstep %}
{% endstepper %}

{% if  %}

## Create an Assemble patient graph

> Assemble a patient graph from FHIR bundle.

```json
{"openapi":"3.1.0","info":{"title":"Clinical Graph (CG) REST API","version":"0.1.0"},"servers":[{"url":"https://cg-api-prod.system.com","description":"Production API"},{"url":"https://cg-api-stage.system.com","description":"Staging API"},{"url":"https://cg-api-dev.system.com","description":"Development API"},{"url":"http://localhost:80","description":"Local API"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"AssembledPatient-Output":{"properties":{"nodes":{"items":{"$ref":"#/components/schemas/AssembleNode-Output"},"type":"array","title":"Nodes","description":"Graph nodes"},"relationships":{"items":{"$ref":"#/components/schemas/AssembleEdge-Output"},"type":"array","title":"Relationships","description":"Graph edges between nodes"},"demographics":{"allOf":[{"$ref":"#/components/schemas/AppApiSchemasAssemblePatientDemographics"}],"description":"Patient demographics"}},"type":"object","required":["nodes","relationships","demographics"],"title":"AssembledPatient","description":"AssembledPatient"},"AssembleNode-Output":{"properties":{"node_type":{"type":"string","title":"Node Type","description":"Discriminator for the node subtype"},"fhir_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Id"},"notable":{"type":"boolean","title":"Notable","description":"Whether this node is notable/important"},"system_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Id"},"system_preferred_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Preferred Name"},"other_system_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Other System Ids"},"coding":{"anyOf":[{"items":{"$ref":"#/components/schemas/ExternalCoding"},"type":"array"},{"type":"null"}],"title":"Coding"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/AssembleNodeMetadata-Output"},{"type":"null"}]}},"type":"object","required":["node_type","fhir_id","notable","system_id","system_preferred_name"],"title":"AssembleNode","description":"AssembleNode"},"ExternalCoding":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System"},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display"}},"type":"object","required":["code","system","display"],"title":"ExternalCoding","description":"ExternalCoding"},"AssembleNodeMetadata-Output":{"properties":{"condition_metadata":{"anyOf":[{"$ref":"#/components/schemas/ConditionMetadata-Output"},{"type":"null"}]},"observation_metadata":{"anyOf":[{"$ref":"#/components/schemas/ObservationMetadata-Output"},{"type":"null"}]},"intervention_metadata":{"anyOf":[{"$ref":"#/components/schemas/InterventionMetadata"},{"type":"null"}]},"allergy_metadata":{"anyOf":[{"$ref":"#/components/schemas/AllergyMetadata-Output"},{"type":"null"}]}},"type":"object","title":"AssembleNodeMetadata","description":"AssembleNodeMetadata"},"ConditionMetadata-Output":{"properties":{"clinicalStatus":{"anyOf":[{"$ref":"#/components/schemas/ClinicalStatusEnum"},{"type":"null"}]},"family_history":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Family History"},"ccsr_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ccsr Categories"},"ccsr_body_systems":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ccsr Body Systems"},"onsetDateTime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Onsetdatetime"},"recordedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Recordeddate"}},"type":"object","required":["clinicalStatus","family_history"],"title":"ConditionMetadata","description":"ConditionMetadata"},"ClinicalStatusEnum":{"type":"string","enum":["active","recurrence","relapse","inactive","remission","resolved","unknown"],"title":"ClinicalStatusEnum","description":"ClinicalStatusEnum"},"ObservationMetadata-Output":{"properties":{"category":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Category"},"interpretation":{"anyOf":[{"$ref":"#/components/schemas/ObservationInterpretationEnum"},{"type":"null"}]},"risk":{"anyOf":[{"$ref":"#/components/schemas/RiskTypeEnum"},{"type":"null"}]},"risk_direction":{"anyOf":[{"$ref":"#/components/schemas/RiskDirectionEnum"},{"type":"null"}]},"observation_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Observation Time"},"valueQuantity":{"anyOf":[{"$ref":"#/components/schemas/QuantityType"},{"type":"null"}]}},"type":"object","required":["risk","risk_direction","observation_time"],"title":"ObservationMetadata","description":"ObservationMetadata"},"ObservationInterpretationEnum":{"type":"string","enum":["carrier","better","significant change down","significant change up","worse","off scale low","off scale high","insufficient evidence","abnormal","critical abnormal","critical high","critical low","high","significantly high","low","significantly low","normal","intermediate","no clsi defined breakpoint","non-susceptible","resistant","synergy - resistant","susceptible","susceptible-dose dependent","synergy - susceptible","outside threshold","above high threshold","below low threshold","indeterminate","equivocal","negative","not detected","positive","detected","expected","unexpected","non-reactive","reactive","weakly reactive"],"title":"ObservationInterpretationEnum","description":"ObservationInterpretationEnum"},"RiskTypeEnum":{"type":"string","enum":["optimal","low","normal","high"],"title":"RiskTypeEnum","description":"RiskTypeEnum"},"RiskDirectionEnum":{"type":"string","enum":["high","very high","low","very low"],"title":"RiskDirectionEnum","description":"RiskDirectionEnum"},"QuantityType":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"comparator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comparator"}},"type":"object","title":"QuantityType","description":"QuantityType"},"InterventionMetadata":{"properties":{"intervention_type":{"allOf":[{"$ref":"#/components/schemas/InterventionTypeEnum"}],"description":"Medication or procedure"},"status":{"anyOf":[{"$ref":"#/components/schemas/InterventionStatusEnum"},{"type":"null"}]},"intervention_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Intervention Time"}},"type":"object","required":["intervention_type","status","intervention_time"],"title":"InterventionMetadata","description":"InterventionMetadata"},"InterventionTypeEnum":{"type":"string","enum":["medication","procedure","immunization"],"title":"InterventionTypeEnum","description":"InterventionTypeEnum"},"InterventionStatusEnum":{"type":"string","enum":["active","on-hold","cancelled","completed","stopped","draft","unknown","entered-in-error","not-done","in-progress"],"title":"InterventionStatusEnum","description":"InterventionStatusEnum"},"AllergyMetadata-Output":{"properties":{"clinicalStatus":{"anyOf":[{"$ref":"#/components/schemas/ClinicalStatusEnum"},{"type":"null"}]},"verificationStatus":{"anyOf":[{"$ref":"#/components/schemas/VerificationStatusEnum"},{"type":"null"}]},"criticality":{"anyOf":[{"$ref":"#/components/schemas/CriticalityEnum"},{"type":"null"}]},"recordedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Recordeddate"}},"type":"object","title":"AllergyMetadata","description":"AllergyMetadata"},"VerificationStatusEnum":{"type":"string","enum":["unconfirmed","confirmed","refuted","entered-in-error"],"title":"VerificationStatusEnum","description":"VerificationStatusEnum"},"CriticalityEnum":{"type":"string","enum":["low","high","unable-to-assess"],"title":"CriticalityEnum","description":"CriticalityEnum"},"AssembleEdge-Output":{"properties":{"source":{"type":"string","title":"Source","description":"system_id of source node"},"target":{"type":"string","title":"Target","description":"system_id of target node"},"relationship_id":{"type":"string","title":"Relationship Id","description":"Relationship identifier of the edge"}},"type":"object","required":["source","target","relationship_id"],"title":"AssembleEdge","description":"AssembleEdge"},"AppApiSchemasAssemblePatientDemographics":{"properties":{"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"race":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Race"}},"type":"object","required":["age","gender","race"],"title":"AppApiSchemasAssemblePatientDemographics","description":"AppApiSchemasAssemblePatientDemographics"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/assemble":{"post":{"tags":["Assemble"],"summary":"Create an Assemble patient graph","description":"Assemble a patient graph from FHIR bundle.","operationId":"assemble","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Assemble In"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssembledPatient-Output"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

{% endif %}

## Assemble API Schema Documentation

### Overview

The Assemble Schema provides a comprehensive data model for representing patient healthcare information as a graph structure. It supports various clinical entities including conditions, observations, interventions, allergies, and immunizations, along with their relationships.

### Table of Contents

1. [Core Models](#core-models)
2. [Supporting Models](#supporting-models)
3. [Metadata Models](#metadata-models)
4. [Enumerations](#enumerations)

***

### Core Models

#### AssembledPatient

The root model representing a complete patient record with all associated clinical data.

**Fields:**

| Field           | Type                  | Required | Description                                                    |
| --------------- | --------------------- | -------- | -------------------------------------------------------------- |
| `nodes`         | `list[AssembleNode]`  | Yes      | List of all clinical entities (conditions, observations, etc.) |
| `relationships` | `list[AssembleEdge]`  | Yes      | Graph edges connecting related nodes                           |
| `demographics`  | `PatientDemographics` | Yes      | Patient demographic information                                |

**Example:**

```json
{
  "nodes": [...],
  "relationships": [...],
  "demographics": {
    "age": 57,
    "gender": "female",
    "race": "White"
  }
}
```

***

#### AssembleNode

Represents a clinical entity in the patient's healthcare graph.

**Fields:**

| Field                   | Type                   | Required | Description                                                                     | Example                      |
| ----------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------- | ---------------------------- |
| `node_type`             | `str`                  | Yes      | Discriminator for the node subtype (condition, observation, intervention, etc.) | `"condition"`                |
| `fhir_id`               | `str`                  | No       | FHIR ID from the original FHIR bundle                                           | `"Condition/12345"`          |
| `notable`               | `bool`                 | Yes      | Whether this node is notable/important                                          | `true`                       |
| `system_id`             | `str`                  | No       | System Interoperable Variable ID                                                | `"SIV:12345"`                |
| `system_preferred_name` | `str`                  | No       | Human-readable name for this entity                                             | `"Type 2 Diabetes Mellitus"` |
| `other_system_ids`      | `list[str]`            | No       | Additional System Interoperable Variable IDs                                    | `["SIV:67890"]`              |
| `coding`                | `list[ExternalCoding]` | No       | External coding references (ICD10, LOINC, etc.)                                 | See ExternalCoding           |
| `metadata`              | `AssembleNodeMetadata` | No       | Node-specific metadata                                                          | See AssembleNodeMetadata     |

**Example:**

```json
{
  "node_type": "condition",
  "fhir_id": "abcdefg1234567",
  "notable": true,
  "system_id": "l2HyYCfEDI",
  "system_preferred_name": "Type 2 diabetes mellitus",
  "other_system_ids": [],
  "coding": [
    {
      "code": "44054006",
      "system": "SNOMED CT core",
      "display": "Diabetes mellitus type 2 (disorder)"
    }
  ],
  "metadata": {
    "condition_metadata": {
      "clinicalStatus": "active",
      "family_history": false
    }
  }
}
```

***

#### AssembleEdge

Represents a relationship between two nodes in the healthcare graph.

**Fields:**

| Field    | Type  | Required | Description                   |
| -------- | ----- | -------- | ----------------------------- |
| `source` | `str` | Yes      | system\_id of the source node |
| `target` | `str` | Yes      | system\_id of the target node |

**Example:**

```json
{
  "source": "abc123",
  "target": "xyz567"
}
```

***

### Supporting Models

#### PatientDemographics

Patient demographic information.

**Fields:**

| Field    | Type  | Required | Description           | Example    |
| -------- | ----- | -------- | --------------------- | ---------- |
| `age`    | `int` | No       | Patient age in years  | `57`       |
| `gender` | `str` | No       | Administrative gender | `"female"` |
| `race`   | `str` | No       | Race as recorded      | `"White"`  |

***

#### ExternalCoding

External coding system reference (ICD10, LOINC, SNOMED, etc.).

**Fields:**

| Field     | Type  | Required | Description                | Example                                            |
| --------- | ----- | -------- | -------------------------- | -------------------------------------------------- |
| `code`    | `str` | No       | External code value        | `"E11.9"`                                          |
| `system`  | `str` | No       | Coding system name         | `"ICD10"`                                          |
| `display` | `str` | No       | Human-readable description | `"Type 2 diabetes mellitus without complications"` |

***

### Metadata Models

#### AssembleNodeMetadata

Container for all possible metadata types for a node. Only one metadata field should be populated based on the node type.

**Fields:**

| Field                   | Type                   | Description                     |
| ----------------------- | ---------------------- | ------------------------------- |
| `condition_metadata`    | `ConditionMetadata`    | Metadata for condition nodes    |
| `observation_metadata`  | `ObservationMetadata`  | Metadata for observation nodes  |
| `intervention_metadata` | `InterventionMetadata` | Metadata for intervention nodes |
| `allergy_metadata`      | `AllergyMetadata`      | Metadata for allergy nodes      |

***

#### ConditionMetadata

Metadata specific to disease or condition nodes.

**Fields:**

| Field               | Type                 | Required | Description                                      |
| ------------------- | -------------------- | -------- | ------------------------------------------------ |
| `clinicalStatus`    | `ClinicalStatusEnum` | No       | Current clinical status of the condition         |
| `family_history`    | `bool`               | No       | True if this is a family history condition       |
| `ccsr_categories`   | `list[str]`          | No       | CSSR categories of the condition                 |
| `ccsr_body_systems` | `list[str]`          | No       | CSSR body system classification of the condition |
| `onsetDateTime`     | `datetime`           | No       | Onset datetime as reported in the EHR            |
| `recordedDate`      | `datetime`           | No       | Recorded datetime as reported in EHR             |

**Example:**

```json
{
  "clinicalStatus": "active",
  "family_history": false,
  "cssr_categories": ["Sleep wake disorders"],
  "cssr_body_system": ["NVS"],
  "onsetDateTime": "2026-01-22T06:00:00Z",
  "recordedDate": "2026-01-23T11:00:00Z"
}
```

***

#### ObservationMetadata

Metadata specific to observation nodes (lab results, vital signs, etc.).

**Fields:**

<table><thead><tr><th>Field</th><th width="156.5703125">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>category</code></td><td><code>list[ObservationCategoryEnum]</code></td><td>No</td><td>Observation category (e.g., vital-signs, laboratory, imaging, social-history)</td></tr><tr><td><code>interpretation</code></td><td><code>ObservationInterpretationEnum</code></td><td>No</td><td>Clinical interpretation (e.g., High, Low, Normal)</td></tr><tr><td><code>risk</code></td><td><code>RiskTypeEnum</code></td><td>No</td><td>Risk bucket (optimal, low, normal, high)</td></tr><tr><td><code>risk_direction</code></td><td><code>RiskDirectionEnum</code></td><td>No</td><td>Directionality of risk</td></tr><tr><td><code>observation_time</code></td><td><code>datetime</code></td><td>No</td><td>When the observation was recorded</td></tr></tbody></table>

**Example:**

```json
{
  "category": ["vital-signs"],
  "interpretation": "abnormal",
  "risk": "high",
  "risk_direction": "high",
  "observation_time": "2026-01-15T00:00:00"
}
```

***

#### InterventionMetadata

Metadata specific to intervention nodes (medications, procedures).

**Fields:**

| Field               | Type                     | Required | Description                                                |
| ------------------- | ------------------------ | -------- | ---------------------------------------------------------- |
| `intervention_type` | `InterventionTypeEnum`   | Yes      | Type of intervention (medication, procedure, immunization) |
| `status`            | `InterventionStatusEnum` | No       | Current status of the intervention                         |
| `intervention_time` | `datetime`               | No       | When the intervention was last updated                     |

**Example:**

```json
{
  "intervention_type": "medication",
  "status": "active",
  "intervention_time": "2026-01-10T08:00:00Z"
}
```

***

#### AllergyMetadata

Metadata specific to allergy nodes.

**Fields:**

| Field                | Type                     | Required | Description                                        |
| -------------------- | ------------------------ | -------- | -------------------------------------------------- |
| `clinicalStatus`     | `ClinicalStatusEnum`     | No       | Clinical status (active, inactive, resolved)       |
| `verificationStatus` | `VerificationStatusEnum` | No       | Verification status (confirmed, unconfirmed, etc.) |
| `criticality`        | `CriticalityEnum`        | No       | Criticality level (low, high, unable-to-assess)    |
| recordedDate         | `datetime`               | No       | When the allergy was recorded                      |

**Example:**

```json
{
  "clinicalStatus": "active",
  "verificationStatus": "confirmed",
  "criticality": "high",
  "recordedDate": "2025-05-10T09:00:00Z"
}
```

***

### Enumerations

#### ClinicalStatusEnum

Clinical status values for conditions and allergies.

**Values:**

| Value        | Description                   |
| ------------ | ----------------------------- |
| `active`     | Condition is currently active |
| `recurrence` | Condition has recurred        |
| `relapse`    | Condition has relapsed        |
| `inactive`   | Condition is inactive         |
| `remission`  | Condition is in remission     |
| `resolved`   | Condition has been resolved   |
| `unknown`    | Status is unknown             |

***

#### RiskTypeEnum

Risk level categorization.

**Values:**

| Value     | Description   |
| --------- | ------------- |
| `optimal` | Optimal range |
| `low`     | Low risk      |
| `normal`  | Normal range  |
| `high`    | High risk     |

***

#### RiskDirectionEnum

Directionality of risk for observations.

**Values:**

| Value       | Description                   |
| ----------- | ----------------------------- |
| `high`      | Risk is from high values      |
| `very high` | Risk is from very high values |
| `low`       | Risk is from low values       |
| `very low`  | Risk is from very low values  |

***

#### ObservationCategoryEnum

Observation category codes. Based on HL7 standards.

| `vital-signs`    |
| ---------------- |
| `laboratory`     |
| `imaging`        |
| `social-history` |
| `procedure`      |
| `survey`         |
| `exam`           |
| `therapy`        |
| `activity`       |

***

#### ObservationInterpretationEnum

Clinical interpretation codes for observations. Based on HL7 standards.

**Common Values** (for a full list of values, see <https://hl7.org/fhir/R4/valueset-observation-interpretation.html>)**:**

| `off scale low`      |
| -------------------- |
| `off scale high`     |
| `abnormal`           |
| `critical abnormal`  |
| `critical high`      |
| `critical low`       |
| `high`               |
| `significantly high` |
| `low`                |
| `significantly low`  |
| `normal`             |
| `intermediate`       |
| `resistant`          |
| `outside threshold`  |
| `negative`           |
| `not detected`       |
| `positive`           |

***

#### InterventionTypeEnum

Type of clinical intervention.

**Values:**

| Value          | Description               |
| -------------- | ------------------------- |
| `medication`   | Medication intervention   |
| `procedure`    | Procedure intervention    |
| `immunization` | Immunization intervention |

***

#### InterventionStatusEnum

Status of an intervention.

**Values:**

| Value              | Description           |
| ------------------ | --------------------- |
| `active`           | Currently active      |
| `on-hold`          | Temporarily on hold   |
| `cancelled`        | Cancelled             |
| `completed`        | Completed             |
| `stopped`          | Stopped               |
| `draft`            | Draft status          |
| `unknown`          | Unknown status        |
| `entered-in-error` | Entered in error      |
| `not-done`         | Not done              |
| `in-progress`      | Currently in progress |

***

#### VerificationStatusEnum

Verification status for allergies.

**Values:**

| Value              | Description       |
| ------------------ | ----------------- |
| `unconfirmed`      | Not yet confirmed |
| `confirmed`        | Confirmed         |
| `refuted`          | Has been refuted  |
| `entered-in-error` | Entered in error  |

***

#### CriticalityEnum

Criticality level for allergies.

**Values:**

| Value              | Description                  |
| ------------------ | ---------------------------- |
| `low`              | Low criticality              |
| `high`             | High criticality             |
| `unable-to-assess` | Unable to assess criticality |

***

### Data Security

The Assemble API does not store customer-submitted input data or any generated patient graphs. All patient identification and data retention are the responsibility of the customer, and must be managed within the customer’s own systems.

The Assemble API processes only the FHIR fields defined in the schema above and will ignore any fields outside that schema. However, customers should avoid transmitting unnecessary PHI and are strongly encouraged to remove direct identifiers (e.g., patient name, address, phone number, email) prior to sending data to the API.