Assemble

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

1

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)

Create an Assemble patient graph

post

https://cg-api-prod.system.comhttps://cg-api-stage.system.comhttps://cg-api-dev.system.comhttp://localhost:80

/v1/assemble

Assemble a patient graph from FHIR bundle.

Authorizations

APIKeyHeader

x-api-keystringRequired

Body

application/json

object · AssembleInOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/v1/assemble

HTTPcURLJavaScriptPython

POST /v1/assemble HTTP/1.1
Host: cg-api-prod.system.com
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "nodes": [
    {
      "node_type": "text",
      "fhir_id": "text",
      "notable": true,
      "system_id": "text",
      "system_preferred_name": "text",
      "other_system_ids": [
        "text"
      ],
      "coding": [
        {
          "code": "text",
          "system": "text",
          "display": "text"
        }
      ],
      "metadata": {
        "condition_metadata": {
          "clinicalStatus": "active",
          "family_history": true
        },
        "observation_metadata": {
          "interpretation": "carrier",
          "risk": "optimal",
          "risk_direction": "high",
          "observation_time": "2026-01-31T12:49:14.635Z"
        },
        "intervention_metadata": {
          "intervention_type": "medication",
          "status": "active",
          "intervention_time": "2026-01-31T12:49:14.635Z"
        },
        "allergy_metadata": {
          "clinicalStatus": "active",
          "verificationStatus": "unconfirmed",
          "criticality": "text"
        }
      }
    }
  ],
  "relationships": [
    {
      "source": "text",
      "target": "text"
    }
  ],
  "demographics": {
    "age": 1,
    "gender": "text",
    "race": "text"
  }
}

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

2. Supporting Models

3. Metadata Models

4. 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:

{
  "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:

{
  "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:

{
  "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

Example:

{
  "clinicalStatus": "active",
  "family_history": false
}

---

ObservationMetadata

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

Fields:

Field	Type	Required	Description
interpretation	ObservationInterpretationEnum	No	Clinical interpretation (e.g., High, Low, Normal)
risk	RiskTypeEnum	No	Risk bucket (optimal, low, normal, high)
risk_direction	RiskDirectionEnum	No	Directionality of risk
observation_time	datetime	No	When the observation was recorded

Example:

{
  "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:

{
  "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	str	No	Criticality level (low, high, unable-to-assess)

Example:

{
  "clinicalStatus": "active",
  "verificationStatus": "confirmed",
  "criticality": "high"
}

---

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

---

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.