Embassy Api

This is the guide to Embassy, an API to the Visiba Care platform. It follows the REST documentation specified by FHIR in the FHIR specification, and takes use of FHIR’s data models.

Accessing the API

To gain development access to the API, contact us at integration@visibacare.com. In the email, include your customer name. If you are not a direct customer but acting on behalf of one of our customers please let us know which one. Further, include a description of what your are aiming to solve with an integration, this helps us learn how our API is used and allow us to provide you with better support.

API endpoints

POST appointment is used for creating appointments. Appointments can be created with practitioners, patients, guests, representatives and a healthcare service.

GET appointment is used for fetching existing appointments. This includes all participants that have been invited to the appointment and additional information that was provided when the appointment was created.

Search appointment can be used with a GET or POST request and is used for searching for appointments. It can be used when wanting appointments in a specific time interval, appointments on a specific healthcare service or appointments belonging to a specific patient.

Patch appointment is used for cancelling and rescheduling appointments.

POST patient is used for creating patients. A patient must exist in Visiba Care before being included in an appointment, if it did not exist on beforehand it can be created here.

GET patient is used for fetching existing patients. When an appointment is retrieved the Visiba Care id of the patient can be fetched and used here to get further details of the patient.

Patch patient is used for updating the phone numbers of patients.

Search patient can be used with a GET or POST request and is used for searching for patients. Given _id can be used to search for a specific patient. Using identifier will allow you to search using another identifier, such as phone number.

GET healthcare service is used for fetching healthcare services. A healthcare service must always be included in an appointment. To get the name of the healthcare service included in an appointment this endpoint can be used.

Search healthcare service can be used with a GET or POST and is used for searching for healthcare services. To know what healthcare services exists that can be used for an appointment this endpoint can be used. It will provide the Visiba care Id and name of the healthcare service.

GET practitioner is used for fetching existing practitioners. When an appointment is retrieved the Visiba Care id of the practitioner can be fetched and used here to get further details of the practitioner.

Search practitioner can be used with a GET or POST and is used for searching for practitioners. Given a healthcare service id this endpoint returns what practitioners that are active on that healthcare service.

GET subscription topic is used for fetching topics available for subscriptions.

POST subscription is used for creating subscriptions. The subscription must be created on an existing subscription topic.

GET subscription is used for fetching existing subscription(s).

Delete subscription is used for deleting existing subscription(s).

Patch subscription is used for patching existing subscription.

POST communication request is used for creating communication requests.

GET communication request is used for fetching existing communication requests.

POST communication is used for creating communications. A communication must link to an existing communication request.

GET communication is used for fetching existing communications.

GET code system is used for fetching code systems with reason codes.

Release information

To view what new features come to Embassy API you can visit our release information.

Updated personal identifiers

We are currently updating national identifiers for the FHIR resources Practitioner, Patient and RelatedPerson. Thus, the documentation for identifying these resources will differ somewhat until this change has been finished. The new identifiers will allow for specifying which country the identifier belongs to, which previously has been done by using the default country for the customer.

FHIR Implementation Guide

Information about our structure definitions specifying our profiles and extensions you can visit our FHIR Implementation Guide.

Authentication

In the request header, specify the following value

{
    "X-Visiba-Care-API-Key": "[Your Api Key]"
}

To gain access to this API, you will need an API key and setup a number of IP-addresses this key will have access from. Reach out to us at Visiba Care if you are interested in this. Note that in the test environment no IP addresses need to be specified, but a key is still required.

Once you have received your key, you can use it in the header X-Visiba-Care-API-Key.

Request Headers

Additional headers

In the request header, specify a content type

{
    "content-type": "[Your content type header]"
}

The content type must be added among the headers in a request. This describes of what type the input data is and is either:

Optional Headers

Prefer header

In the request header, you may specify a prefer header

{
    "prefer": "[Your prefer header]"
}

There is a possibillity to include an optional header prefer which specifies a preffered return data for a request. It is either:

If not specified the server will return a full resource according to if the header representation was chosen.

Accept header

In the request header, you may specify a accept header

{
    "accept": "[Your accept header]"
}

There is another optional header accept which specifies the preferred type of the returned data. It can be either:

If not specified the server will return the json representation of the return body.

Response headers

Request Id

Response id header format:

{
    "X-Request-Id": "[Your request id]"
}

All requests towards Embassy will get a request identifier as a response header. The request id is used when more information regarding a request is needed from Visiba Care support.

Appointment

Appointment resource

An appointment resource

{
  "resourceType": "Appointment",
  "id": "[Appointment Id provided by Visiba Care]",
  "status": "booked",
  "description": "[Optional description of appointment]",
  "start": "[Start time]",
  "end": "[End time]",
  "appointmentType": {
    "coding": [
     {
      "system": "http://schema.visibacare.com/codesystem/appointment/appointmenttype",
      "code": "[Digital or Physical]"
     }
    ]
   },
  "contained": [ ... ],
  "participant": [ ... ]
}

The appointment resource is used to describe appointments in Visiba Care. See information about the separate fields below.

Input fields

Practitioner participant that is a primary performer

{
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-participant-id-extension",
      "valueUri": "[Visiba appointment participant id]"
    }
  ],
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
          "code": "PPRF"
        }
      ]
    }
  ],
  "actor": {
    "type": "Practitioner",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "status": "accepted"
}

Practitioner participant that is not a primary performer

{
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-participant-id-extension",
      "valueUri": "[Visiba appointment participant id]"
    }
  ],
  "actor": {
    "type": "Practitioner",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "status": "accepted"
}

Patient participant that identifies a patient in Visiba Care

{
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-participant-id-extension",
      "valueUri": "[Visiba appointment participant id]"
    },
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-ticket-extension",
      "valueUri": "[Appointment ticket]"
    },
    { - Only set if a list price exists
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/list-price-extension",
      "valueMoney": { "value": 5.55, "currency": "EUR" }
    }
  ],
  "actor": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "status": "accepted"
}

Related person / patient participant that refers to a contained resource of id 1

{
  "extension": [ 
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-participant-id-extension",
      "valueUri": "[Visiba appointment participant id]"
    },
    { - Only set if representative
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/appointment-ticket-extension",
      "valueUri": "[Appointment ticket]"
    }
  ],
  "actor": {
    "reference": "#1",
    "type": "RelatedPerson / Patient"
  },
  "status": "accepted"
}

Healthcare service participant

{
  "actor": {
    "type": "HealthcareService",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "status": "accepted"
}

Participants

There are different types of participants that can be included in a meeting.

Practioners is referenced by an Identifier. Exactly one practitioner has to be indicated as the primary performer of the appointment and this practitioner must be able to practice on the healthcare service the appointment is to take place at. This can be identified using multiple identifier systems:

Patients can be included in multiple ways depending on their use case. A patient that is represented by a representative is referenced by an Reference and refers to a contained resource where the patient is defined by setting the reference to #[containedId]. In the contained list there must be a resource of type Patient that has an Id that is [containedId].

A patient that is not represented is identified by an Identifier. There are multiple ways to identify a patient:

Related persons always refer to a contained resource of type Related Person by setting the reference to #[containedId]. In the contained list there must be a resource of type Related Person that has an Id that is [containedId]. The related person includes a name containing a given name, surname and the text name combining them both. It includes telecom containing email and/or phone number where available. Representatives further includes an identifier with a national identification number where available. Guests does not include more information, though representatives include a reference to a patient in the Patient field, referencing to a contained patient. Further, the Relationship of a representative will have one coding stating Representative.

One HealthcareService always exists for an appointment and is referenced by an Identifier. This can be identified using one identifier systems:

Regarding the amount of participants there can be a maximum of 10 participants in an appointment, disregarding the healthcare service where the appointment gets registered at. Note that a representative and the patient this represents count as one participant.

POST /Appointment

Used to create an appointment in Visiba Care. The input data must include participants, start and end time, status and possibly a description of the appointment taking place. The reply states either that the appointment was created, or that an error occured while creating. This error is sent as an Operation Outcome.

Response types

Defining a related person

A related person to add to the contained list

{
    "resourceType": "RelatedPerson",
    "id": "[containedId]",
    "identifier": [
    {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
    }
    ],
    "patient": { - Only set if representative
    "reference": "#[patientContainedId]",
    "type": "Patient"
    },
    "relationship": [ - Only set if representative
    {
        "coding": [
        {
            "system": "http://schema.visibacare.com/codesystem/relatedperson/relationship",
            "code": "Representative"
        }
        ]
    }
    ],
    "name": [
    {
        "text": "[Given name and surname]",
        "family": "[Surname]",
        "given": [
        "[Given name]"
        ]
    }
    ],
    "telecom": [
    {
        "system": "email",
        "value": "[Email]"
    },
    {
        "system": "phone",
        "value": "[Phone]"
    }
    ]
}

There are many rules concerning how to define a related person, so let us go in to detail about this.

There can be multiple names for a Related person. To know which we should use we check the use of the name and first chooses one with the use Usual, then Official and if none are found we take the first name.

It can be defined what language a related person prefers for their notifications. This is specified in the communication field. We check the first entry for the first Language.Coding entry with the system http://hl7.org/fhir/ValueSet/languages and use that value. If no language is specified we will use the default language of the customer, whereas if the specified language is not supported by the customer we return an error.

It can be defined what country a related person belongs to. This is specified in the address list. We take the first entry in the Address.Country and check for a valid country code. Here we make the same validation as for the language.

The telecom defines how to reach out to a related person and must have email and/or phone number specified. For email we accept the Contact point system Email and for phone we accept either Phone or Sms, however we will prioritize Phone if both exist. If there are multiple phone/email entries with different use we use this priority order: Mobile, Home, Work. If none of these exists we will use the first entry in the telecom list for email/phone respectively.

A related person that is a guest may have certain email/phone requirements depending on what authentication method the related person gets, which is always the default authentication method for the country of related persons / guests for that customer. However, we always require that at least one of email/phone is specified so that we have a way of contacting the guest that they are invited to an appointment.

A related person that is a representative must specify what patient it represents by refering to a contained patient in the Patient field and setting the Relationship field to a Codeable Concept with the system http://schema.visibacare.com/codesystem/relatedperson/relationship and the value Representative.

A representative can exist in Visiba Care on beforehand. Because of this we will attempt to first find the representative by making use of the first identifier we find in the Identifier field which can be:

If the representative is found we will ignore any other information apart from which patient it refers to. This means that if you are sure that the representative exists on beforehand you may skip to add other personal information about the representative. On the other hand, if it is not found we will attempt to create it using the informatin obtained from the related person resource.

Error codes

GET /Appointment/{appointment_id}

Used to get an appointment using its Visiba Care appointment id. This id is returned in the Appointment.Id field from us after a successful creation of an appointment or when searching for appointments. A successful response includes the found FHIR appointment.

Response types

Query Parameters

PATCH /Appointment/{appointment_id}

A parameters resource for cancellation

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/status"
        },
        {
          "name": "value",
          "valueCode": "cancelled"
        }
      ]
    }
  ]
}

A parameters resource for rescheduling

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/start"
        },
        {
          "name": "value",
          "valueDateTime": "[New start time]"
        }
      ]
    },
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/end"
        },
        {
          "name": "value",
          "valueDateTime": "[New end time]"
        }
      ]
    }
  ]
}

Used to update an appointment in Visiba Care on the customer sending the request. The patch request consists of a query parameter, appointment_id, and a body in either xml or json consisting of a Parameters. Currently we support cancelling or rescheduling an appointment. Both of these are not allowed in the same request. The response either shows that the updating succeeded or failed. Any error is sent as an Operation Outcome.

Response types

Input fields

Error codes

SEARCH /Appointment or /Appointment/_search

A bundle resource

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "link": [
    {
      "relation": "next",
      "url": "[Url to the next page of the search]"
    }
  ],
  "entry": [
    {
      "fullUrl": "[Url to this appointment if fetched by a GET]",
      "resource": { ... },
      "search": {
        "mode": "match"
      }
    }
  ]
}

A search for appointments returns all appointments matching the requirements given. It can be requested using a GET (Endpoint: /Appointment) or a POST (Endpoint: /Appointment/_search). The difference between these calls is that either the parameters to the search is provided in the query params for a GET and in a body for a POST.

The search has some optional parameters, but if the parameter _id is used, the search will only try to find an apointment with this specific id. A successful response returns a FHIR bundle of found appointments.

If not all appointments that were found could be included in the response bundle, an url will be presented that can be used to get to the next page of the response. If no appointments were found the response will be an empty bundle.

Response types

Input parameters/fields

Return body

Error codes

Patient

Patient resource

A patient resource

{
  "resourceType": "Patient",
  "id": "[Patient id provided by Visiba Care]",
  "identifier": [ -- Only required if national identification number is required on customer
    {
      "system": "http://schema.visibacare.com/identifier/patient/nationalidentificationnumber",
      "value": "[National identification number]"
    }
  ],
  "name": [
    {
      "text": "[Given name and surname]",
      "family": "[Surname]",
      "given": [
        "[Given name]"
      ]
    }
  ],
  "telecom": [
    {
      "extension": [ -- Ignored in input but shared by Visiba Care in output
        {
          "url": "https://schema.visibacare.com/fhir/StructureDefinition/patient-consent-extension",
          "valueBoolean": true
        }
      ],
      "system": "[Contact point system for this telecom entry]",
      "value": "[Phone or email information]"
    },
  ],
  "address": [ -- Ignored in input but shared by Visiba Care in output
    {
      "country": "SE"
    }
  ]
}

The patient resource is used to describe patients in Visiba Care. See information about the separate fields below.

Input fields

POST /Patient

A patient resource used for input

{
  "resourceType": "Patient",
  "identifier": [ -- Only required if national identification number is required on customer
    {
      "system": "http://schema.visibacare.com/identifier/patient/nationalidentificationnumber",
      "value": "[National identification number]"
    }
  ],
  "name": [
    {
      "text": "[Given name and surname]",
      "family": "[Surname]",
      "given": [
        "[Given name]"
      ]
    }
  ],
  "telecom": [
    {
      "system": "[Contact point system for this telecom entry]",
      "value": "[Phone or email information]"
    },
  ]
}

Used to create a patient in Visiba Care on the customer sending the requests. The patient may be sent in the body of the request as either xml or json. The reply states either that the patient was created, or that an error occured while creating. This error is sent as an Operation outcome.

Note that in the input the patient consent extensions are ignored by us and are as default set to true, but when a patient is retrieved these will hold the most recent consent updates for the patient. They are updated when a patient logs in and changes them. Further, the country information is ignored and the country specified for the patient will always be the default for the customer. When a patient is retrieved it can be viewed what country information the patient has.

Response types

Error codes

GET /Patient/{patient_id}

Used to get a patient using its Visiba Care patient id.

Response types

Query Parameters

PATCH /Patient/{patient_id}

PATCH Patient example

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/telecom.where(system = 'phone')"
        },
        {
          "name": "value",
          "valueString": "[Phone number]"
        }
      ]
    },
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/telecom.where(system = 'email')"
        },
        {
          "name": "value",
          "valueString": "[Email]"
        }
      ]
    },
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/name.given"
        },
        {
          "name": "value",
          "valueString": "[Given name]"
        }
      ]
    },
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/name.family"
        },
        {
          "name": "value",
          "valueString": "[Family name]"
        }
      ]
    }
  ]
}

Used to update a patient using its id. There is support for updating a patient's name, family name, telephone number and/or email. Note that if the customer of your API key has telephone number set as a unique identifier for patients, it is not allowed to update the telephone number. In the patch request you can patch one or multiple details for the patient by adding one or multiple Operation entries in the parameters list, see the example.

Response types

Input fields

Error codes

SEARCH /Patient or /Patient/_search

A bundle resource

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "next",
      "url": "[Url to the next page of the search]"
    }
  ],
  "entry": [
    {
      "fullUrl": "[Url to this patient if fetched by a GET]",
      "resource": { ... },
      "search": {
        "mode": "match"
      }
    }
  ]
}

A search for patients returns all patients matching the requirements given. It can be requested using a GET (Endpoint: /Patient) or a POST (Endpoint: /Patient/_search). The difference between these calls is that either the parameters to the search is provided in the query params for a GET and in a body for a POST.

The search has some optional parameters, but if the parameter _id is used, the search will only try to find a patient with this specific id. A successful response returns a FHIR bundle of found patients. The bundle can not contain more than one patient in this case.

Response types

Input parameters/fields

Identifier example

identifier=http://schema.visibacare.com/identifier/nationalidentificationnumber/se|199105012398

identifier=http://schema.visibacare.com/identifier/patient/phonenumber|467000000000

identifier=http://schema.visibacare.com/identifier/patient/visibaid|12345

Available identifier are:

Return body

Error codes

HealthcareService

Healthcare Service resource

A healthcare service resource

{
  "resourceType": "HealthcareService",
  "id": "[Healthcare service id provided by Visiba Care]",
  "name": "[Name of healthcare service]",
}

The healthcare service resource is used to describe where an appointment takes place, the reception of the appointment. See information about the separate fields below.

Input fields

GET /HealthcareService/{healthcareservice_id}

Used to get a healthcare service using its Visiba Care id.

Response types

Query Parameters

SEARCH /HealthcareService or /HealthcareService/_search

A bundle resource

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "link": [
    {
      "relation": "next",
      "url": "[Url to the next page of the search]"
    }
  ],
  "entry": [
    {
      "fullUrl": "[Url to this healthcare service if fetched by a GET]",
      "resource": { ... },
      "search": {
        "mode": "match"
      }
    }
  ]
}

A search for healtcare services returns all healthcare services matching the requirements given. It can be requested using a GET (Endpoint: /HealthcareService) or a POST (Endpoint: /HealthcareService/_search). The difference between these calls is that either the parameters to the search is provided in the query params for a GET and in a body for a POST.

The search has some optional parameters, but if the parameter _id is used, the search will only try to find a healthcare service with this specific id. A successful response returns a FHIR bundle of found healthcare services.

If not all healthcare services that were found could be included in the response bundle, an url will be presented that can be used to get to the next page of the response. If no healthcare services were found the response will be an empty bundle.

Response types

Input parameters/fields

Return body

Error codes

Practitioner

Practitioner resource

A practitioner resource

{
  "resourceType": "Practitioner",
  "id": "[Practitioner id provided by Visiba Care]",
  "identifier": [
    { -- Country-specific national identity number (e.g "se" country code for Swedish)
      "system": "http://schema.visibacare.com/identifier/nationalidentificationnumber/{country-code}",
      "value": "[National identifier of practitioner]"
    },
    { -- Only for Swedish practitioners
      "system": "http://schema.visibacare.com/identifier/practitioner/hsaid",
      "value": "[Hsa id of practitioner]"
    }
  ],
  "name": [
    {
      "text": "[Given name and surname]",
      "family": "[Surname]",
      "given": [
        "[Given name]"
      ]
    }
  ],
  "telecom": [
    {
      "system": "email",
      "value": "[Email of practitioner]"
    }
  ]
}

The practitioner resource is used to describe practitioners in Visiba Care. See information about the separate fields below.

Input fields

GET /Practitioner/{practitioner_id}

Used to get a practitioner using its Visiba Care practitioner id.

Response types

Query Parameters

SEARCH /Practitioner or /Practitioner/_search

A bundle resource

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "link": [
    {
      "relation": "next",
      "url": "[Url to the next page of the search]"
    }
  ],
  "entry": [
    {
      "fullUrl": "[Url to this practitioner if fetched by a GET]",
      "resource": { ... },
      "search": {
        "mode": "match"
      }
    }
  ]
}

A search for practitioners returns all practitioners matching the requirements given. It can be requested using a GET (Endpoint: /Practitioner) or a POST (Endpoint: /Practitioner/_search). The difference between these calls is that either the parameters to the search is provided in the query params for a GET and in a body for a POST.

The search has some optional parameters, but if the parameter _id is used, the search will only try to find a practitioner with this specific id. A successful response returns a FHIR bundle of found practitioner.

If not all practitioners that were found could be included in the response bundle, an url will be presented that can be used to get to the next page of the response. If no practitioners were found the response will be an empty bundle.

Practitioners are users in Visiba Care that are performers on at least one healthcare service.

Response type

Input parameters/fields

Return body

Error codes

CommunicationRequest

Communication Request resource

A communication request resource

{
  "resourceType": "CommunicationRequest",
  "id": "[CommunicationRequest id provided by Visiba Care]",
  "status": "[CommunicationRequest status]",
  "subject": "[Subject of the communication request]",
  "recipient": "[Recipients of the communication request]",
  "sender": "[Sender of the communication request]",
  "requester": "[Requester of the communication request]",
  "payload": [
    {
      "content": {
        "contentString": "[Reason text]"
      }
    }
  ],
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/patient-response-enabled-extension",
      "valueBoolean": "[Patient is allowed to respond]"
    }
  ],
  "reasonCode": [
    {
      "coding": [
        {
          "system": "https://example.com/CodeSystem/HealthcareService.xyz.ReasonCode",
          "code": "[Reason code]"
        }
      ]
    }
  ],
  "contained": "[...]",
}

The communication request resource is used to describe a conversation belonging to a healthcare service between a patient and one or more practitioners. Currently, the API allows initiating conversations between a patient and a healthcare service or a patient and one or multiple practitioners.

For more information, see the fields below.

Input fields

POST /CommunicationRequest

A communication request resource used to initiate a conversation by a practitioner

{
  "resourceType": "CommunicationRequest",
  "status": "active",
  "subject": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "recipient": [
    {
      "type": "HealthcareService",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    },
    {
      "type": "Practitioner",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    },
    {
      "type": "Patient",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    }
  ],
  "sender": {
    "type": "Practitioner",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "requester": {
    "type": "Practitioner",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "payload": [
    {
      "content": {
        "contentString": "Reason text"
      }
    }
  ],
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/patient-response-enabled-extension",
      "valueBoolean": false
    }
  ]
}

A communication request resource used to initiate a conversation by a patient

{
  "resourceType": "CommunicationRequest",
  "status": "active",
  "subject": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "recipient": [
    {
      "type": "HealthcareService",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    },
    {
      "type": "Patient",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    }
  ],
  "sender": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "requester": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "reasonCode": [
    {
      "coding": [
        {
          "system": "https://example.com/CodeSystem/HealthcareService.xyz.ReasonCode",
          "code": 1
        }
      ]
    }
  ],
  "payload": [
    {
      "content": {
        "contentString": "Reason text"
      }
    }
  ],
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/patient-response-enabled-extension",
      "valueBoolean": true
    }
  ]
}

A communication request used to initiate a conversation as a representative

{
  "resourceType": "CommunicationRequest",
  "contained": [
    {
      "resourceType": "RelatedPerson",
      "id": "a7d77c57-1fec-42f8-ad63-5a94ef37b299",
      "identifier": [
        {
          "system": "http://schema.visibacare.com/identifier/relatedPerson/nationalidentificationnumber",
          "value": "[Identifier value]"
        }
      ],
      "patient": {
        "reference": "#7dfd7cad-6c02-445b-b2a7-79ff085109c3",
        "type": "Patient"
      },
      "relationship": [
        {
          "coding": [
            {
              "system": "http://schema.visibacare.com/codesystem/relatedperson/relationship",
              "code": "Representative"
            }
          ]
        }
      ],
      "name": [
        {
          "text": "GivenName Surname",
          "family": "Surname",
          "given": [
            "GivenName"
          ]
        }
      ],
      "telecom": [
        {
          "system": "email",
          "value": "[Email]"
        },
        {
          "system": "phone",
          "value": "[Phone number]"
        }
      ]
    },
    {
      "resourceType": "Patient",
      "id": "7dfd7cad-6c02-445b-b2a7-79ff085109c3",
      "identifier": [
        {
          "system": "http://schema.visibacare.com/identifier/patient/nationalidentificationnumber",
          "value": "[Identifier value]"
        }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://schema.visibacare.com/fhir/StructureDefinition/patient-response-enabled-extension",
      "valueBoolean": true
    }
  ],
  "status": "active",
  "subject": {
    "reference": "#7dfd7cad-6c02-445b-b2a7-79ff085109c3",
    "type": "Patient"
  },
  "payload": [
    {
      "contentString": "Reason text"
    }
  ],
  "requester": {
    "reference": "#a7d77c57-1fec-42f8-ad63-5a94ef37b299",
    "type": "RelatedPerson"
  },
  "recipient": [
    {
      "type": "HealthcareService",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    },
    {
      "reference": "#a7d77c57-1fec-42f8-ad63-5a94ef37b299",
      "type": "RelatedPerson"
    },
    {
      "reference": "#7dfd7cad-6c02-445b-b2a7-79ff085109c3",
      "type": "Patient"
    }
  ],
  "sender": {
    "reference": "#a7d77c57-1fec-42f8-ad63-5a94ef37b299",
    "type": "RelatedPerson"
  },
  "reasonCode": [
    {
      "coding": [
        {
          "system": "https://example.com/CodeSystem/HealthcareService.xyz.ReasonCode",
          "code": 1
        }
      ]
    }
  ],
}

This endpoint is used to initiate a new conversation in Visiba Care, which can be done by either a patient, a representative or a practitioner. This is denoted by the sender and the requester fields, which currently must be identical to each other in the input. The input data must also include a subject, a list of recipients including the healthcare service, a payload containing a single reason message and an extension that dictates whether the patient has permission to respond. Additionally, a reason code can be specified.

If a patient initates the request, it can only be sent to a healthcare service, and not specific practitioners. A practitioner at that healthcare service is then able to pick up the conversation in Visiba Care and will consequently become the primary performer of it. Likewise, the patient response extension cannot be set to false when the conversation is patient-initiated, as this is not supported.

When a representative initiates the request it can only be sent to a healthcare service and not to specific practitioner. The communication request must include both the patient of the representative and the representative itself. The representative must be the sender, and the patient in question must be the subject. Both of these participants must be stated as literal references, namely that they reference a contained resource. The contained patient requires a personal identification number and the contained representative (a RelatedPerson) must state a releationship being 'Representaive' and refer to the contained patient in its Patient field.

The reply states either that the conversation was created, or that an error occurred while creating. This error is returned in the form of a FHIR operation outcome.

Notifications in Visiba Care will be sent.

Response types

Error codes

GET /CommunicationRequest/{communicationrequest_id}

A GET endpoint used to retrieve a communication request by its Visiba Care id.

Response types

Query Parameters

Communication

Communication resource

A communication resource

{
  "resourceType": "Communication",
  "id": "[Communication id provided by Visiba Care]",
  "basedOn": "[Reference to an existing communication request]",
  "status": "completed",
  "sent": "[Timestamp specifying when the message was sent]",
  "sender": "[Sender of the communication]",
  "payload": "[Payload containing the message text]",
  "contained": "[...]"
}

The communication resource is used to describe a message in a conversation between a patient and one or more practitioners, or a representative and one or more practitioners. It must include a logical reference to a valid communication request in the basedOn field.

For more information, see the fields below.

Input fields

POST /Communication

A communication used to represent a message sent by a patient

{
  "resourceType": "Communication",
  "status": "completed",
  "basedOn": [
    {
      "type": "CommunicationRequest",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    }
  ],
  "sender": {
    "type": "Patient",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "payload": [
    {
      "content": {
        "contentString": "Message to be sent"
      }
    }
  ]
}

A communication used to represent a message sent by a representative

{
  "resourceType": "Communication",
  "contained": [
    {
      "resourceType": "RelatedPerson",
      "id": "a7d77c57-1fec-42f8-ad63-5a94ef37b299",
      "identifier": [
        {
          "system": "http://schema.visibacare.com/identifier/relatedPerson/nationalidentificationnumber",
          "value": "[Identifier value]"
        }
      ],
      "patient": {
        "reference": "#7dfd7cad-6c02-445b-b2a7-79ff085109c3",
        "type": "Patient"
      },
      "relationship": [
        {
          "coding": [
            {
              "system": "http://schema.visibacare.com/codesystem/relatedperson/relationship",
              "code": "Representative"
            }
          ]
        }
      ],
      "name": [
        {
          "text": "GivenName Surname",
          "family": "Surname",
          "given": [
            "GivenName"
          ]
        }
      ],
      "telecom": [
        {
          "system": "email",
          "value": "[Email]"
        },
        {
          "system": "phone",
          "value": "[Phone number]"
        }
      ]
    },
    {
      "resourceType": "Patient",
      "id": "7dfd7cad-6c02-445b-b2a7-79ff085109c3",
      "identifier": [
        {
          "system": "http://schema.visibacare.com/identifier/patient/nationalidentificationnumber",
          "value": "[Identifier value]"
        }
      ]
    }
  ],
  "status": "completed",
  "basedOn": [
    {
      "type": "CommunicationRequest",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    }
  ],
  "sender": {
    "reference": "#a7d77c57-1fec-42f8-ad63-5a94ef37b299",
    "type": "RelatedPerson"
  },
  "payload": [
    {
      "content": {
        "contentString": "Message to be sent"
      }
    }
  ]
}

A communication used to represent a message sent by a practitioner

{
  "resourceType": "Communication",
  "status": "completed",
  "basedOn": [
    {
      "type": "CommunicationRequest",
      "identifier": {
        "system": "[Identifier system]",
        "value": "[Identifier value]"
      }
    }
  ],
  "sender": {
    "type": "Practitioner",
    "identifier": {
      "system": "[Identifier system]",
      "value": "[Identifier value]"
    }
  },
  "payload": [
    {
      "content": {
        "contentString": "Message to be sent"
      }
    }
  ]
}

A POST endpoint for creating new communication resources, which describe messages to existing communication requests.

The reply states either that the conversation was created, or that an error occurred while creating. This error is returned in the form of a FHIR operation outcome.

Notifications in Visiba Care will not be sent currently.

Response types

GET /Communication/{communication_id}

A GET endpoint used to retrieve a communication by its Visiba Care id.

Response types

Query Parameters

CodeSystem

Code system resource

A code system resource

{
  "resourceType": "CodeSystem",
  "id": "[The id of the code system]",
  "url": "[The URL of the code system]",
  "status": "active",
  "count": 2,
  "concept": [
    {
      "code": "[Reason code]",
      "display": "[Reason name]"
    },
    {
      "code": "[Reason code]",
      "display": "[Reason name]"
    }
  ]
}

The code system resource is used to return all available reason codes for a given healthcare service.

For more information, see the fields below.

Input fields

GET /CodeSystem/HealthcareService.{healthcareservice_id}.ReasonCode

A GET endpoint used to retrieve a code system with reason codes by its Visiba Care healthcare service id.

Response types

Query Parameters

Subscriptions

Subscriptions allow clients to get notifications when data changes.
Visiba defines the topics available to subscribe to. For the time being these are:

Client requests available subscription topics by calling GET ../SubscriptionTopic/. Client creates a subscription to a topic, with a selected channel to get notifications to, by calling POST ../Subscription/.

Channels

Currently, we support the rest-hook and email channels for notifications.
Please contact us if you would like to see support for other channels.

FHIR subscription channels

GET /SubscriptionTopic

Get SubscriptionTopic example response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "SubscriptionTopic",
        "id": "1",
        "url": "https://example.com/SubscriptionTopic/1",
        "title": "AppointmentCreated",
        "status": "active",
      },
    }
  ]
}

Used to get topics available for subscriptions. The id returned in the body is used when creating a subscription.

GET /SubscriptionTopic/{subscriptiontopic_id}

Used to get specific topic by id.

Response types

Query Parameters

Subscription resource

The subscription resource is used to describe subscriptions in Visiba Care. See information about the separate fields below.

Input fields

POST /Subscription

POST Subscription example

{
  "resourceType": "Subscription",
  "reason": "Client Testing",
  "channel": {
    "endpoint": "https://clientendpoint.com/Endpoints/a67f0cd8-6fb9-4036-968c-ae525f4b604a",
    "payload": "application/fhir+json",
    "_payload": {
      "extension": [
        {
        }
      ]
    },
    "type": "rest-hook",
    "header": [
      "testkey=testvalue"
    ]
  },
  "status": "requested",
  "criteria": "http://example.com/SubscriptionTopic/1",
}

Used to create a subscription.

Response types

Error codes

GET /Subscription

Used to get a list of all subscriptions that has been created for the Api key. A successful response includes all found FHIR subscriptions.

Response types

GET /Subscription/{id}

Used to get a subscription using its id. This id is returned in the Id field from us after a successful creation of a subscription. A successful response includes the found FHIR subscription.

Response types

Query Parameters

GET /Subscription/{id}/$status

Used to get a subscription status using its id. This id is returned in the Id field from us after a successful creation of a subscription. A successful response includes the found FHIR subscription status.

Response types

Query Parameters

GET /Subscription/$status

Used to get a list of subscription statuses for all subscriptions that has been created for the Api key. A successful response includes all found FHIR subscription statuses.

Response types

GET /Subscription/{Id}/$events

Get Subscription status with events example

{
    "resourceType": "Bundle",
    "type": "history",
    "entry": [
      {
      "resource": {
        "resourceType": "SubscriptionStatus",
        "status": "active",
        "type": "query-event",
        "eventsSinceSubscriptionStart": "2",
        "notificationEvent": [
          {
          "eventNumber": "1",
          "focus": {
            "reference": "http://example.com/Appointment/41599"
            }
          },
          {
          "eventNumber": "2",
          "focus": {
            "reference": "http://example.com/Appointment/41753"
            }
          },
        ],
        "subscription": {
          "reference": "http://example.com/Subscription/41"
        },
        "topic": "http://example.com/SubscriptionTopic/1"
       }
      }
    ]
}

Used to get the subscription status for a subscription, including all events (if there are any). A successful response includes the requested FHIR subscription status and a list of events.

Response types

DELETE /Subscription

Used to delete all subscriptions for the Api key.

Response types

DELETE /Subscription/{Id}

Used to delete a specific subscription, using its Id as identifier.

Response types

Query Parameters

PATCH /Subscription/{subscription_id}

PATCH Subscription example

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {
          "name": "type",
          "valueCode": "replace"
        },
        {
          "name": "path",
          "valueString": "/status"
        },
        {
          "name": "value",
          "valueString": "off"
        }
      ]
    }
  ]
}

Used to update a subscription using its id. This id is returned in the Id field from us after a successful creation of a subscription or when getting all subscriptions. For the time being, the only supported operation via patch is to update the status of the subscription (active/off).

Response types

Input fields

Error codes

Event notification resource

This describes the payload you receieve from an event. Delivered as json in a web request (web hook) or as payload in an email.

This is a Bundle of the resource SubscriptionStatus.

Event notification resource example.

{
  "resourceType": "Bundle",
  "type": "history",
  "entry": [
    {
      "resource": {
        "resourceType": "SubscriptionStatus",
        "status": "active",
        "type": "event-notification",
        "eventsSinceSubscriptionStart": "0",
        "notificationEvent": [
          {
            "eventNumber": "1",
            "focus": {
              // The location of the resources that triggered this event. 
              // In this case an appointment has been updated.
              "reference": "https://embassy-test.visibacare.com/Appointment/325135"
            }
          }
        ],
        "subscription": {
          // The location of the subscription that triggered this event.
          "reference": "https://embassy-test.visibacare.com/Subscription/2060"
        },
        // refers to AppointmentUpdated
        "topic": "https://embassy-test.visibacare.com/SubscriptionTopic/3"
      }
    }
  ]
}```

Support

Prerequisites

To get the best help possible, please provide us with the request id, which is returned from a request as a Response Header

Contact

Contact us: integration@visibacare.com