Seegnal Common API v4

Overview

Base URL: https://{seegnal domain}/intg/api

The Common API exposes three endpoints:

Process Therapy — evaluate the patient's therapy.
Update EMR — pull finalized recommendations back into the EHR.
Update Medication Portfolio — keep customer and Seegnal catalogues aligned.

TenantId must be sent on every request — via Header (preferred for POST), QueryString (preferred for GET), or Body. Example: IL-XX-5K8A1.

Download OpenAPI schema (JSON)

General Notes

Notation:

Y — Mandatory. Failure to provide fails the entire request.
Y* — Mandatory, but missing it will not fail the request (flagged in the response).
– — No default; the EMR must send a valid value.
[] — Initialize with an empty array.

If a mandatory field has a default value, the property may be omitted when the default applies (e.g. PrescriberRole).
Non-mandatory properties may be removed from the request based on Tenant needs.
datetime accepts any value parseable by C# DateTime.Parse.
Appendixes (codes, units) live in Seegnal Integration Appendixes vX.X.xlsx.

1. Process Therapy

POST

https://{seegnal domain}/intg/api/Therapy/ProcessTherapy

Core clinical engine endpoint. The EHR posts the patient's current state — demographics, medications, lab results, diagnoses — and receives alerts, recommendations, and a secure UI session link.

Source: EHR
Target: Seegnal
Function: Process Therapy
Content-Type: application/json

Headers

#	Field	Type	Description
1	Cache-Control	string	no-cache
2	Content-Type	string	application/json
3	TenantId	string	Tenant ID provided by Seegnal (e.g. IL-XX-5K8A1)

Request

#	Field	Type	Default	Description	Req.
1	TherapyId	string	-	Request Identifier (Guid).	Y
2	TherapyRefTime	datetime	utc.now	Time patient was admitted to therapy.
3	TenantId	string	-	The Healthcare/EMR Provider Id.	Y
4	PrescriberId	string	-	User (physician) unique identifier.	Y
5	PrescriberSpecialty	string	null	Physician specialty.
6	PatientId	string	-	Patient unique identifier.	Y
7	PrescriberRole	int	1	1 - Doctor (default) 2 - Nurse 3 - Pharmacist 4 - Practitioner Nurse 5 - Intern Doctor	Y
8	AdmitTime	datetime	null	e.g. 2009-06-15 13:45:30 Patient hospitalization time
9	DischargeTime	datetime	null	e.g. 2009-06-15 13:45:30
10	DischargeType	int	null	1 - Home 2 - Transfer hospital
11	EncounterId	string	null	Visit number.
12	EncounterStatus	int	null	1 - Inpatient 2 - Outpatient Hospitalized locally or from other facility
13	InstitutionType	int	0	0 - Unset (take default by tenant configuration at Seegnal) 1 - Community 2 - Hospital 3 - Pharmacy
14	DepartmentCode	string	null
15	DepartmentName	string	null
16	PatientType	int	0	0 - Default (default) 1 - Oncologic
17	BirthDate	datetime	-	e.g. 2009-06-15 13:45:30	Y
18	NeonateBirthAgeWeeks	decimal	null	Gestational age of premature baby in weeks (up to 44).
19	Gender	int	-	0 – Male 1 – Female	Y
20	RecordType	int	-	1 – Admission 3 – Hospitalization 4 – Discharge 6 – Outpatient 7 – Control screen (in Prometheus) 10 – ER visit
21	PatientFactors	PatientFactor[]	null
22	PatientHeights	PatientHeight[]	null
23	PatientWeights	PatientWeight[]	null
24	Ethnicity	string	null
25	Race	string	null
26	Allergies	Allergy[]	null
27	LabTests	LabTest[]	null
28	GeneticTests	GeneticTest[]	null
29	Medications	Medication[]	-	Must contain at least 1 medication.	Y
30	Diagnoses	Diagnosis[]	null
31	Diets	Diet[]	null

Response

#	Field	Type	Description
1	TherapyId	string	Request identifier.
2	UISessionId	string	UI Session ID.
3	SeegnalUrl	string	Link to Seegnal user interface.
4	IndicatorStatus	int	0–No Alerts 1–Alerts 2–Bypasses 3–Pending 9–Error (e.g. timeout, internal, security)
5	AlertsCount	int	Count of alerts.
6	BypassCount	int	Count of bypasses.
7	AlertGroups	AlertGroup[]
8	ResponseStatus	object

Process Therapy — Request sample

{
  "therapyId": "5212ab90-d65f-4d60-912f-c44e5f8b66cb",
  "tenantId": "CO-XX-XXXXX",
  "therapyRefTime": "2022-01-01",
  "prescriberId": "1798",
  "prescriberSpecialty": "Doctor",
  "patientId": "1234567",
  "prescriberRole": 1,
  "admitTime": "2019-03-17",
  "dischargeTime": "2019-03-17",
  "dischargeType": 1,
  "encounterId": "ABC-1234/D",
  "encounterStatus": 1,
  "institutionType": 2,
  "departmentCode": "20",
  "departmentName": "Cardiology",
  "patientType": 1,
  "birthDate": "1960-02-23",
  "neonateBirthAgeWeeks": null,
  "recordType": 3,
  "gender": 1,
  "patientWeights": [
    { "value": 82.4, "unit": 1, "time": "2019-03-17" }
  ],
  "patientHeights": [
    { "value": 173, "unit": 1, "time": "2019-03-17" }
  ],
  "ethnicity": null,
  "race": null,
  "patientFactors": [
    { "key": 1, "time": "2019-03-17" }
  ],
  "allergies": [
    { "code": "8738", "codeScheme": 1 }
  ],
  "labTests": [
    {
      "code": "1975-2",
      "codeScheme": 1,
      "value": 2,
      "unit": "µmol/l",
      "measurementTime": "2021-12-17",
      "valueTime": "2021-12-17",
      "measurementSite": null,
      "testType": 1,
      "resultInterpretation": 1
    },
    {
      "code": "1888-2",
      "codeScheme": 1,
      "value": 2,
      "unit": "µmol/l",
      "measurementTime": "2021-12-17",
      "valueTime": "2021-12-17",
      "measurementSite": null,
      "testType": 1,
      "resultInterpretation": 1
    }
  ],
  "geneticTests": [
    {
      "geneticID": 279,
      "phenotype": "Poor Metabolizer",
      "genotype": "*5/*5",
      "time": "2017-03-17"
    }
  ],
  "medications": [
    {
      "orderId": "12479d89-6fdf-452a-af1b-bfb70d1f4416",
      "medCodeScheme": 1,
      "medCode": "8738",
      "medName": "DAPAGLIFLOZIN",
      "medStatusIndicator": 2,
      "prescribedTime": "2022-01-01",
      "orderStartTime": "2022-01-01",
      "orderEndTime": "2022-01-01",
      "lastAdministrationTime": "2022-01-03",
      "purchasedDateTime": "2022-01-02",
      "medSource": 2,
      "administrationRoute": "64",
      "dosage": {
        "doseUnit": "28",
        "doseAmount": 2000,
        "doseFrequency": 20,
        "frequencyType": 0,
        "doseType": 0,
        "treatmentDuration": 20,
        "administrationTiming": [
          "2019-03-13 13:18:27",
          "2019-03-14 13:18:27",
          "2019-03-17 16:18:27",
          "2019-03-17 20:18:27"
        ],
        "timeOfDay": [1, 3, 4],
        "onceEveryXPeriod": [1, 2],
        "xDaysInPeriod": [5, 4],
        "doseRate": null,
        "doseRateUnit": null,
        "doseVolume": null,
        "doseVolumeUnit": null
      },
      "prnConditional": null,
      "prnReason": null
    },
    {
      "orderId": "12479d89-6fdf-452a-af1b-bfb70d1f4416",
      "medCodeScheme": 1,
      "medCode": "6954",
      "medName": "ESOMEPRAZOLE",
      "medStatusIndicator": 2,
      "prescribedTime": "2022-01-01",
      "orderStartTime": "2022-01-01",
      "orderEndTime": "2022-01-01",
      "lastAdministrationTime": "2022-01-03",
      "purchasedDateTime": "2022-01-02",
      "medSource": 2,
      "administrationRoute": "64",
      "dosage": { "doseUnit": "28", "doseAmount": -1 }
    },
    {
      "orderId": "12479d89-6fdf-452a-af1b-bfb70d1f4416",
      "medCodeScheme": 1,
      "medCode": "3941",
      "medName": "CLOPIDOGREL",
      "medStatusIndicator": 2,
      "prescribedTime": "2022-01-01",
      "orderStartTime": "2022-01-01",
      "orderEndTime": "2022-01-01",
      "lastAdministrationTime": "2022-01-03",
      "purchasedDateTime": "2022-01-02",
      "medSource": 2,
      "administrationRoute": "64",
      "dosage": { "doseUnit": "28", "doseAmount": -1 }
    }
  ],
  "diagnoses": [
    { "codeScheme": 11, "code": "250.0", "time": "2019-03-17" },
    { "code": "V58.11", "codeScheme": 11, "time": "2021-11-28" }
  ],
  "diets": [
    { "code": "73", "codeScheme": 0 }
  ]
}

Process Therapy — Response sample

{
  "therapyId": "5212ab90-d65f-4d60-912f-c44e5f8b66cb",
  "uiSessionId": "5212ab90-d65f-4d60-912f-c44e5f8b66cb",
  "seegnalUrl": "https://{seegnal domain}/intg/api/Therapy/RedirectToWebApp?session=5212ab90...",
  "alerts": [
    {
      "involvedEntities": [
        { "id": "6954", "type": 1, "medCodeScheme": 1, "effectMode": 2 }
      ],
      "bypassReason": null,
      "bypassDescription": null
    }
  ]
}

2. Update EMR

POST

https://{seegnal domain}/intg/api/Therapy/UpdateEMR

Pulls finalized clinical recommendations back into the EHR. EMRs with a direct communication channel are invoked with the response via a pre-agreed trigger.

Source: EHR
Target: Seegnal
Function: Update EMR
Content-Type: application/json

Request

#	Field	Type	Default	Description	Req.
1	UISessionId	string	-	UI Session ID.	Y

Response

#	Field	Type	Description
1	TherapyId	string	Original identifier of the calculated response.
2	UISessionId	string	UI Session ID.
3	UserOperations	UserOperation[]	See section 2.0 null if no user operations were made
4	IndicatorStatus	int	0–No Alerts 1–Alerts 2–Bypasses 3–Pending 9–Error (e.g. timeout, internal, security)
5	MedRcmds	MedRcmd[]	See section 2.1 null if UpdateEMR was not submitted on web

2.0 — UserOperation

#	Field	Type	Description
1	OperationType	int	0 - None 1 - Bypass 2 - Unbypass
2	AlertGroups	AlertGroup[]	This represents the full state of all interactions if exist

Update EMR — Request sample

{ "uiSessionId": "14ef2d05-d5ec-4ac7-85ba-541b73ed2177" }

Update EMR — Response sample

{
  "therapyId": "d01eb544-479a-177c-d168-753b763414d7",
  "uiSessionId": "14ef2d05-d5ec-4ac7-85ba-541b73ed2177",
  "userOperations": [
    {
      "operationType": 1,
      "alertGroups": [
        {
          "alertType": 1,
          "alertSeverity": "2",
          "alertSynopsis": "Interacting drugs/patient factors...",
          "involvedEntities": [
            { "id": "4868",  "type": 1, "medCodeScheme": 1, "effectMode": 2 },
            { "id": "25257", "type": 1, "medCodeScheme": 1, "effectMode": 2 }
          ],
          "bypassReason": null,
          "bypassDescription": null
        }
      ]
    }
  ],
  "indicatorStatus": 3,
  "medRcmds": [
    { "actionType": 1, "orderId": null,          "medCodeScheme": 1, "medCode": "92875", "medName": "KADCYLA VIALS 100 MG" },
    { "actionType": 2, "orderId": "CurrentVis3", "medCodeScheme": 1, "medCode": "50168", "medName": "TRAJENTA TAB 5MG F.C (30)" },
    { "actionType": 2, "orderId": "CurrentVis4", "medCodeScheme": 1, "medCode": "32630", "medName": "(30) MICROPIRIN TAB 100MG" }
  ]
}

3. Update Medication Portfolio

POST

https://{seegnal domain}/intg/api/Catalog/UpdateMedsPortfolio

Source: EHR
Target: Seegnal
Function: Update Meds Portfolio
Content-Type: application/json

This API is used to keep both Customer's and Seegnal's medication catalog aligned. Before the "go live" in a new customer there is a manually medication mapping process to align both catalogs. After "go live" the changes in the e-medication catalogue are transmitted using this API.

Any change to the medication catalogue on the customer side should be sent to Seegnal. It could be due to any reason like: New medication added to the catalogue, Medication was updated (either mapping code/type was changed or drug name changed), Medication was removed from the customer's medication catalogue, Medication was suspended (temporary or permanently unavailable for a new prescription, but it may be active in old prescriptions).

During the mapping process, the customer's mapping specialist needs to find the best match for their drug in Seegnal's catalogue based on its properties (considering active ingredient(s), dose strength, dose form and route of administration). Seegnal's catalogue is exposed via a web site (AKA also as Diff-Reff). Once matched, the mapping specialist needs to add the GCN (Seegnal's medication ID) next to the customer medication ID as well as the mapping type. This is the mapping that should be sent using this API.

There are items in the customer catalogue that are not considered as medications (such as nutrients or medical supplements). Those items are not needed to be sent to Seegnal for calculation and there is no need to map them. If they will be sent to Seegnal in a "Process Therapy" API they will result in an error message on the medication level. To prevent that the customer need to map them and marked them as "Excluded from clinical calculation" in the mapping process.

For more information on the mapping process and clinical considerations, please refer to "Drug Mapping Procedure CL-10-022(05)".

Request

#	Field	Type	Default	Description	Req.
1	RequestID	string	-	Request unique ID (Guid).	Y
2	TenantId	string	-	The Healthcare Provider Id (Customer Id).	Y
3	MedUpdates	MedUpdate[]	-		Y

Response

#	Field	Type	Description
1	RequestID	string	Request unique ID.
2	StatusCode	int	0 Success · 1 Error · 2 FailMeds (see Errors).
3	SuccessCount	int	Count of successful meds.
4	FailedCount	int	Count of failed meds.
5	Errors	ErrorItem[]

Update Portfolio — Request sample

{
  "requestId": "090ea367-92d0-499d-a94c-44f3b5ffd654",
  "tenantId": "IL-XX-5K8A1",
  "medUpdates": [
    {
      "actionType": 1,
      "medCodeScheme": 1,
      "medCode": "656232",
      "seegnalRefMedCode": "3096",
      "medName": "COUMADIN tab 5mg",
      "medShortName": "COUMADIN",
      "mappingType": 2,
      "rank": 5,
      "isActive": true
    },
    {
      "actionType": 2,
      "medCodeScheme": 1,
      "medCode": "656232",
      "seegnalRefMedCode": "3096",
      "medName": "BISOPROLOL (CARDILOC) 2.5 mg",
      "medShortName": "BISOPROLOL",
      "mappingType": 1,
      "rank": 0,
      "isActive": false
    },
    {
      "actionType": 3,
      "medCodeScheme": 1,
      "medCode": null,
      "seegnalRefMedCode": "3096",
      "medName": "ACETYLSALICYLIC ACID (CARTIA E.C.TAB) 100 mg",
      "medShortName": "ACETYLSALICYLIC",
      "mappingType": 1,
      "rank": 0,
      "isActive": true
    }
  ]
}

Update Portfolio — Response sample

{
  "requestId": "090ea367-92d0-499d-a94c-44f3b5ffd654",
  "statusCode": 2,
  "errors": [
    { "code": 2, "obj": "Med", "prop": "MedCode", "value": null, "index": 2, "note": null }
  ],
  "successCount": 2,
  "failedCount": 1
}

Version History

Show version history

4.2.0 (15.09.25) — ProcessTherapy: Separate medication Dosage into its own object (table 1.7.1; backward compatible). Added Practitioner Nurse and Intern Doctor roles.
4.0.6 (22.01.24) — ProcessTherapy: Add Gender to InvolvedEntity.Type. UpdateEMR: Add Modify action and MedRcmdDosage on MedRcmd.
4.0.3 (30.10.24) — ProcessTherapy: Change OnceEveryXPeriod and XDaysInPeriod from int[] to decimal[].
4.0.0 (07.09.24) — ProcessTherapy: Rename Diagnostics → Diagnoses.
3.2.10 (01.03.24) — Add Home to MedStatusIndicator.
3.2.9 (01.06.23) — Add Purchased, Prescribed, Maintenance to MedStatusIndicator.
3.2.8 (25.04.23) — Add IngredientComposition to Allergy.
3.2.5 (15.03.23) — Add 'Site Blocker' to web hosting on browser-based EHRs.
3.2.0 (01.07.22) — Add MedName for trace purpose.
3.1.9 (12.04.22) — Add Current to MedStatusIndicator.
3.1.5 (16.01.22) — Added default headers and JSON samples.
3.1.2 (13.12.21) — Change DoseFrequency from int to decimal.
3.1.0 (18.11.21) — Add Continuous to FrequencyType; add DoseRate/DoseRateUnit/DoseVolume/DoseVolumeUnit; AdministrationRoute → string.
3.0.13 (01.08.21) — Add BypassReason and BypassDescription to AlertGroup.
3.0.9 (03.05.21) — DoseFrequency int → decimal.
3.0.5 (15.03.21)
- ProcessTherapy:
  - Add AlertDescription to AlertGroup.
  - Add InstitutionType.
  - DoseAmount no longer mandatory (if -1 or omitted, dosage properties are ignored).
  - Remove DosageIncluded.
  - TreatmentDuration int → decimal.
  - AdministrationRoute not mandatory and added to dosage logic.
- UpdateEMR:
  - Add MedName to MedRcmd.
2.3 (09.09.20)
- ProcessTherapy:
  - LabTest.AbnormalIndicator → ResultInterpretation (default Unset).
  - Medication.MedCodeScheme enum re-ordered.
  - Response IndicatorStatus updated.
  - PrescriberRole now fails the request.
  - Medication.AdministrationTiming changed to datetime[] only.
  - Add TimeOfDay, OnceEveryXPeriod, XDaysInPeriod.
  - Updated PatientFactor key values.
  - Added SNOMED-CT (8) key to Diagnoses.
  - Medication PRNConditional & PRNReason.
  - Add BypassCount to response.
  - Add Age to InvolvedEntity.Type.
  - Add TherapyRefTime.
  - Moved RecordType from Medication to Therapy.
- UpdateIndicator removed (joined with UpdateEMR).
- UpdateEMR:
  - Add UserOperations[], IndicatorStatus, SeegnalUrl.
  - MedUpdates → MedRcmds.
  - MedRcmds.MedCodeScheme enum re-ordered.
  - InvolvedEntity.EntityId → ID (enum), EntityType → Type (enum).
  - EffectMode → enum.
  - Add TempBypassed to AlertGroup AlertType.
  - Remove SeegnalURL from response.
  - Add None (0) to UserOperation.
- UpdateMedPortfolio:
  - MedUpdate.MedCodeScheme enum re-ordered.
  - SeegnalRefMedCode mandatory if EMR code scheme selected.
  - ShortMedName → MedShortName.
  - Add IsActive (default true).
  - MedName charset restricted.
  - FailMeds → Errors.
  - Added InvalidOperation error code.
2.2 (14.01.20)
- Typo fix Schema → Scheme.
- ProcessTherapy:
  - Moved Creatinine to Appendix A lab tests.
  - Moved QTc Interval to Appendix A vital signs.
  - Removed Biochemistry, BloodGases, Hematology from LabTest type and Appendix.
  - Response ErrorItem updated.
  - Removed MedName, DoseStrength from Medication.
  - DoseUnit → string.
  - Add UISessionId to response.
  - Modified Allergy CodeScheme.
  - Add Appendix F & G for Allergy.
  - Add Index to ErrorItem.
  - AbnormalIndicator → int (enum), mandatory (Y*).
  - LabTest.Value → decimal.
- UpdateIndicator: add UISessionId.
- UpdateEMR: add UISessionId.
- UpdateMedPortfolio: rename MedActionType → ActionType.
2.1 (01.01.20)
- ProcessTherapy:
  - PrescriberRole default 1 (Doctor), does not fail the request.
  - NeonateBirthAgeWeeks int → decimal.
  - Remove Unit default on PatientWeight/PatientHeight.
  - Remove SeegnalRefMedCodeScheme and SeegnalRefMedCode from Medication.
  - DoseType default 2 (maintenance).
  - Remove PatientID from response.
  - Response AlertGroup add AlertId.
  - Remove Diagnostic SourceType.
  - AdministrationTiming extended to dates or enums (optional).
- UpdateIndicator:
  - Remove PatientID and RequestId.
  - Add Time.
  - Add SeegnalUrl for traffic-light link.
- UpdateMedPortfolio: remove Attributes and Time.
2.0 (31.12.19) — New Common API.