API documentation for integrating device data
Blood glucose monitors and smartwatches to an electronic patient record: REST endpoints, JSON and XML payloads, OAuth authentication, and Swiss-side FHIR profiles. Everything you need to test a first flow before planning a deployment.
Architecture overview
The Vitalink API receives device data, normalizes it, and then exposes it or writes it to your target system. It relies on REST conventions and FHIR resources. Your client application communicates with our endpoints; we handle the conversion and normalization, saving you from writing a parser for every manufacturer.
Monitor or watch that emits its measurements; you don't change anything on its end.
Receives, converts, and normalizes measurements into read-ready FHIR resources.
Calls the endpoints and decides what to do next: display, write, or queue.
Electronic patient record, or a middleware layer you prefer to keep in control.
Main REST endpoints
Read · write · searchThe routes follow modern web conventions for retrieving and writing resources. Each endpoint specifies the accepted parameters and response codes. The exact route names and schemas are in the full reference; the list below is to guide you.
Access rights to these routes are governed by OAuth and your clinical architecture; the full reference covers every parameter and response code.
OAuth authentication
Access to the endpoints is via OAuth. You obtain a token, then use it for your requests. Authorization scopes are defined by role and resource, which limits what a client can read or write. Access rights should be thought through with your clinical architecture and deployment environment from the conceptual phase.
Measurement flows circulate encrypted and access logs remain attached to each client's authorized scope. The details of algorithms, keys, and retention are described on the security and encryption page, along with the division of responsibilities between Vitalink and your institution.
See the security and encryption pageJSON and XML formats
FHIR relies on REST, JSON, and XML depending on the documentation consulted. You choose the format suited to your stack.
- JSON Convenient for web and mobile applications, and for quick tests.
- XML Still present in some hospital environments and legacy tools.
- Same resource Both formats follow the same structure; the choice does not affect the data model.
FHIR profiles and resources
Resources by measurement typeA blood glucose measurement is represented via an observation resource, attached to a patient and a device. Time series from a watch require a structure adapted to the volume. Vitalink documents the resources used for each type of measurement; you then align these resources with your institution's profiles.
Point-in-time blood glucose
A dated measurement, linked to an identified patient and device. This is the most direct case to validate in the test environment.
- Observation resource and its components
- Standardized unit of measurement before writing
- Link to the emitting device
Watch series
Multiple points close in time: the transport structure matters as much as the measurement itself, especially over long periods.
- Batch sending rather than call-by-measurement
- Explicit time window in the request
- Order and timestamp preserved
Your profiles
A CH Core profile or an internal facility profile: you retain control over the final version of the resources.
- Alignment with the hospital's target profile
- Mandatory fields identified before writing
- Compliance check on your pipeline side
Device data normalization
Consumer devices vary in units, codes, and date formats. The API applies semantic normalization before writing. Without this step, each integration becomes a translation in its own right.
Measurement units are converted to a single repository before writing, to compare measurements from different manufacturers.
The same type of measurement must carry the same code, otherwise your patient record receives fragmented series.
Date and time zone formats are unified, which avoids silent shifts in long series.
Clinical codes are aligned with recognized repositories such as SNOMED CT, whether your facility already uses them or not.
Normalization does not stop at units. Observation codes, device types, and clinical repositories must be aligned with your target. Vitalink documents the supported terminologies and how to map your codes; you retain control over the final profile.
Writing to the EHR and middleware
You can write directly to your system or use a middleware layer. This layer absorbs the flows, applies authorization rules, and feeds the target system. It avoids dispersing device logic across multiple services. The choice depends on your architecture and compliance constraints.
Direct writing when your team already masters the target profile and access rules. Using middleware when multiple device sources, multiple care units, or multiple target systems must coexist.
Tests, environments, and versioning
A test environment allows you to validate your flows before going into production. You can reproduce use cases there: point-of-care blood glucose, time series, patient metadata. Responses follow the same format as in production, which reduces surprises during deployment.
Consult enterprise pricingWhat should be prepared before testing a flow? Open
A set of measurements representative of your devices, test patient and device identifiers, and your facility's target profile. Preparing these three elements before the first request avoids most back-and-forth.
How is versioning managed? Open
Endpoints evolve with FHIR profiles and clinical needs. Versioning allows you to maintain a stable integration while a new version is being prepared. Changes are documented before they are made available; plan for this step in your schedule.
What rights should be provided for users on your side? Open
Authorization scopes are defined by role and by resource. A development team does not need the same rights as a care department. Defining these roles early simplifies production rollout and internal auditing.
Where can I find the complete route reference? Open
The complete reference covers each route, its parameters, and its response codes. It is provided with access to the test environment so that your team works on the same version as the one deployed in production.
Compliance and data protection
Health data is subject to strict rules. Vitalink HealthData AG documents its compliance with the Swiss Federal Act on Data Protection (FADP) and the European General Data Protection Regulation (GDPR) on the dedicated page, which specifies the processing bases, retention periods, and the rights of data subjects.
- Swiss Federal Act on Data Protection Processing, retention, and rights of individuals, described for a healthcare facility context.
- European Regulation The GDPR applies to flows that extend beyond Switzerland; the distribution of roles is explained there without jargon.
- Subcontracting What Vitalink processes on your behalf, and what remains under your responsibility as a facility.
Vitalink HealthData AG, Seefeldstrasse 45, 8008 Zürich. Support Monday to Friday, 09:00 – 18:00 (CET).
Before starting integration
Do we need a FHIR server on our side? Open
No. You can consume the endpoints from your existing application. A dedicated FHIR server becomes useful if you wish to host certain resources yourself or cross-reference multiple device sources.
Can we keep our own clinical codes? Open
Yes. Normalization is applied upstream, and the mapping to your internal repositories remains documented. You decide on the final profile used by your facility.
How long does an initial integration take? Open
The first flow validated in the test environment usually arrives before work on the facility-specific profiles. The total duration then depends on your access rules and the number of measurement types to cover.
How do I get access to the test environment? Open
The request is made from the contact page, specifying your facility, the types of devices involved, and the target system. A technical exchange follows to define the scopes before access is opened.
A first flow, then a planned deployment
The goal of this documentation is simple: to allow you to test a first flow before planning a deployment. Once the endpoints, formats, and rights are understood, the rest depends on your architecture and compliance constraints.