NAV
json

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. Here you can create, cancel and alter appointments and there are also some helper functionality to ease the appointment management.

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.

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.

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.

Release information

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

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.

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:

Content type Returns
application/fhir+json Return the body as a FHIR json.
application/fhir+xml Return the body as a FHIR xml.

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:

Prefer Returns
minimal Return no body.
representation Return the full body.
operationOutcome Return a FHIR operation outcome with information about the request will be returned.

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:

Accept Returns
application/fhir+json Return the body as a FHIR json.
application/fhir+xml Return the body as a FHIR xml.

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

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]",
  "contained": [ ... ],
  "participant": [ ... ]
}

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

Input fields

Field name Description
Id Visiba Care identifier of the appointment. Is ignored if defined in input.
Status The status of the appointment. cancelled if the appointment has been cancelled, otherwise booked.
Description A text field stating the reason this appointment was booked visible to both patient and practitioner. If no texted reason has been stated, this field will not exist.
Start The expected start time of the appointment, with minute precision.
End The expected end time of the appointment, with minute precision.
Participant List of appointment participants. This includes all patients and practitioners included in the appointment, any related person (e.g a guest or representative) and the healthcare service where the appointment is to take place.
Participant.Type Only exist for the primary practitioner of the appointment. System is http://terminology.hl7.org/CodeSystem/v3-ParticipationType and with value PPRF (primary performer). Will always exist on exactly one practitioner.
Participant.Actor A resource reference to either a practitioner, patient, related person or healthcare service.
Participant.Actor.Type The participant type. Can be a practitioner, patient, related person or healthcare service.
Participant.Identifier Set for participants that are referenced to Visiba Care and not to a contained resource. Currently this is the case for the healthcare service, the patients that are not represented and all practitioners. This contains an identifier system and a value.
Participant.Status Always accepted for all participants.
Participant.Reference Set for resources that refers to contained participants. This is the case for patients that are represented, the related person representing these and a related person that is a guest.
Contained Includes related persons, that can be either guests or representatives, and patients which are represented. If no such participants are in the meeting this is excluded.

Practitioner participant that is a primary performer

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

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

Patient participant that identifies a patient in Visiba Care

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

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

Identify by Identifier System Comment
HSA-Id http://schema.visibacare.com/identifier/practitioner/hsaid Swedish users only.
Visiba Id http://schema.visibacare.com/identifier/practitioner/visibaid
Email http://schema.visibacare.com/identifier/practitioner/email Not recommended since it may change for a user, however might be useful while testing.

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:

Identify by Identifier System
Personal number http://schema.visibacare.com/identifier/patient/nationalidentificationnumber
Visiba Id http://schema.visibacare.com/identifier/patient/visibaid
Email http://schema.visibacare.com/identifier/patient/phonenumber

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:

Identify by Identifier System
Visiba Id http://schema.visibacare.com/identifier/healthcaresservice/visibaid

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

Response code Explanation
201 Success, includes created appointment body.
400 Bad request, failed FHIR resource validation.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
422 Unprocessable entity, there was an error processing the input data.

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:

Identify by Identifier System
Personal number http://schema.visibacare.com/identifier/relatedperson/nationalidentificationnumber
Visiba Id http://schema.visibacare.com/identifier/relatedperson/visibaid
Email http://schema.visibacare.com/identifier/relatedperson/phonenumber

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

Error Explanation
OnlyBookedStatusSupported Status was either missing or was not of the type booked.
StartTimeIsRequired / EndTimeIsRequired Start/end time was not present.
StartTimeMustNotHaveSecondsOrMillisecondsSet / EndTimeMustNotHaveSecondsOrMillisecondsSet Start/end time has seconds or milliseconds set, we do not support this precision in appointments.
InvalidDuration The duration of the appointment was less than 1 minute, we do not support this.
TooCloseToAppointmentStart The appointment takes place too soon in the future, it is not allowed by customer settings to book an appointment this close to the actual appointment.
PatientNotFound A patient was not found on the customer and need to be created before trying to setup an appointment again.
PatientIdentifierNotSupported / PatientIdentifierValueNotDefined The identifier specified for a patient/representative is not supported.
ConflictingPatientsFound / ConflictingRepresentativesFound The given identifier of a patient/representative was not unique, it must be.
AllRelatedPersonsMustBeContained This can occur for two reasons, either there was related persons in the Appointment.Participant list that did not have a contained id or not all contained ids had corresponding related persons in the Appointment.Contained list.
RelatedPersonInvalidName / InvalidName A related person must have some kind of name, state at least one of the Given name or the Family name for a guets and both Given name and Family name for a representative.
RelatedPersonMustHaveOneValidContactPoint There must exist at least one way of contact with a related person. Either state a phone number or an email.
NoDefaultAuthenticationForCountryOfRelatedPerson The chosen country was valid but there was no default authentication method for it on the customer.
EmailRequiredForRelatedPersonGivenDefaultAuthentication / PhoneNumberRequiredForRelatedPersonGivenDefaultAuthentication / EmailRequired / PhoneRequired Email/phone was required for the authentication method for the related person but was not specified.
InvalidPhoneNumberOfRelatedPerson / InvalidEmailOfRelatedPerson / InvalidPhone / InvalidEmail Email/phone was incorrectly defined.
RelatedPersonInvalidCountry / RelatedPersonInvalidLanguage The requested country/language was not supported by the customer settings.
AllPractionersAreNotAvailable At least one of the requested practitioners was not available at the specified time of the appointment.
PractitionerNotFound A practitioner was not found on the customer.
AtleastOnePractitionerRequired At least one practitioner is required for an appointment but none was found.
ExactlyOnePractitionerShouldBePrimaryPerformer Exactly one practitioner should be the primary performer of the appointment but this was not the case.
PractitionerIdentifierValueInvalid The value of the identifier belonging to a practitioner was invalid.
PractitionerIdentifierValueNotDefined The value of the identifier belonging to a practitioner did not exist.
PractitionerIdentifierNotSupported The identifier system of a practitioner was not supported.
PrimaryPerformerNotFound The primary performer was not found on the customer.
PrimaryPerformerNotFoundOnHealthcareService The primary performer must exist on the healthcare service but this was not the case.
HealthcareServiceMustHaveVisibaCareId The healthcare service must have an identifier with a visiba id, but this was not the case.
HealthcareServiceNotFound The healthcare service was not found on the customer.
ExactlyOneHealthcareServiceRequired There has to be exactly one healthcare service in the appointment, but this was not the case.
InvalidParticipants The Actor or the Actor.Type field was missing from a participant but is required.
ParticipantError An error occured with the participants when attempting to book the appointment in Visiba care. It could be that there are too many participants, that a patient or practitioner did not exist on the customer or that there were duplicates among the participants.
InvalidAmountOfParticipants There has to be at least 2 participant in the meeting, not counting the healthcare service, but this was not the case.
InvalidNationalIdentityNumber / NationalIdentityNumberRequired The national identification number specified when creating a representative was invalid/required.
PatientOfRelatedPersonNotFound The patient referenced from the representative could not be found in the appointment.
NameOfPatientOfRelatedPersonInvalid Name of patient of representative must have either given name or family name set.
NationalIdentificationOfPatientOfRelatedPersonInvalid A nationalidentification number of patient of related person must exist.

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

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
404 Appointment with id {appointment_id} was not found on the customer.

Query Parameters

Parameter Required Description Default Value
appointment_id Yes The Visiba Care identifier of the appointment. N/A

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

Response code Explanation
200 Ok, successful.
400 Bad request, failed FHIR resource validation.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
404 Appointment with id {appointment_id} was not found on the customer.
422 Unprocessable entity, there was an error processing the input data.

Input fields

Field Explanation
Parameter List of updates that are requested. An update describes either a status change (cancellation), start time change or end time change (rescheduling).
Parameter.Name Is always operation.
Parameter.Part The actual updating request parts. Three parts must be included, the type which describes what type of change that is requested, the path which describes the path to the update element, and lastly the value which describes the value to update to. Is the same type as Parameters.Parameter.
Parameter.Part.Name The name of a part of the update, can be either type, path or value.
Parameter.Part.Value[x] An element that can be of any type and depends on what part it is. For a type part this must be a FHIR code. The value of it must be replace in our update cases. For a path part this must be a FHIR string. The value of it can either be /status for a cancellation, /start for updating the start time and /end for updating the end time. For a value part the enforced type depends on what update is requested. For a status update this must be a FHIR code, for a start or end update this must be a FHIR Datetime.

Error codes

Error Explanation
OnlyCancelledStatusSupported The request asked to update the appointment status to something other than cancelled.
InvalidDataType The Parameter.Part.Value was not of the correct type.
StartAndEndRequiredForRescheduling Rescheduling was attempted, but request only included either a start update or an end update, but not both.
OnlyOperationParametersSupported The Parameter.Name was not operation.
ParameterValueUndefined The Parameter.Part.Value was undefined.
ParameterTypeAndPathCombinationNotSupported The combination of the two parts type and path was not valid.
StartMustComeBeforeEnd The new start time was after the new end time.
DateTimeMustBeWholeMinutes Datetime specified seconds or milliseconds.
StartMustBeInTheFuture The new start time was not in the future.
TooLateToUpdateAppointment It was too late to reschedule the appointment due to business rules.
AppointmentCancelled The appointment was already cancelled and could not be updated.
TooLateToCancelAppointment It was too late to cancel the appointment due to businesss rules.
ScheduleConflicts Could not complete the rescheduling since there were scheduling conflicts when doing so.
PrimaryPerformerNotFoundForAppointment There was no associated primary performer for the appointment, such appointments cannot be updated.
BothCancelAndRescheduleCannotBeRequested It is not supported to cancel and reschedule an appointment in the same request.

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

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
422 Unprocessable entity, there was an error processing the input data.

Input parameters/fields

Parameter/Field Explanation Default
healthcareServiceId Specifies a healthcare service to search by. N/A
_id Specifies an id of an appointment to search for. All other parameters will be igonored if this exists. N/A
start Start time of a time interval to search between. Appointment with a start time >= will be included in the resulting set. Required if end is set. N/A
end End time of a time interval to search between. Appointment with a end time <= will be included in the resulting set. Required if start is set. N/A
skip Defines how many appointments of the found appointments should be skipped before inserting them in the response bundle. 0
_count Defines how many appointments of the found appintments should be inserted in the response bundle. Maximum 30. 0
patientId, patientNationalIdentificationNumber, patientPhone Specifies patient details to search by, one or multiple can be used and we will use all specified for the patient of the appointment. N/A

Return body

Field Explanation
Type Is always searchset for this search bundle.
Total Includes the total number of appointments that were found given the input parameters.
Link A list of links and their relation to this bundle.
Link.Relation The relation of the link. Currently we only specifiy links defining how to request for the next page for the search set. Is therefor next if it exists.
Link.Url A link that can be used to do an action of the specified relation. For a next-link this can be requested to the API to get the next page.
Entry A list of bundle entries of found appointments.
Entry.FullUrl An API-specific url to the appointment in the entry.
Entry.Resource The appointment for the entry as a GET request would display it.
Entry.Search Search related information.
Entry.Search.Mode Will always be match.

Error codes

Error Explanation
SkipMustBePositive Skip must be >= 0 .
CountMustBePositive Count must be >= 0.
StartAndEndTimeIsRequired If start is specified end must be specified. If end is specified start must be specified.
StartTimeMustOccurBeforeEndTime Start time must occur before end time.
ParticipantFilterRequired There has to be at least one participant filter specified, among these are health care service and patient related filters.
HealthcareServiceIdNotFound The healthcare service id was not found on the customer.
OnlyCancelledStatusSupported The request asked to update the appointment status to something other than cancelled.
StartTimeMustNotHaveSecondsOrMillisecondsSet / EndTimeMustNotHaveSecondsOrMillisecondsSet Start/end time must not have seconds or milliseconds set.
InvalidNationalIdentificationNumber The specified patient national identification number filter was invalid.
InvalidNationalIdentificationNumber The specified patient phone filter was invalid.

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

Field name Description
Id Visiba Care identifier of the patient. Is ignored if defined in input.
Identifier The personal identification number of the patient. This is required if national identification number is required in the customer configuration.
Name A FHIR HumanName for the patient containing Given with the given name, family with the surname, and the Text combining them both.
Telecom A list of ContactPoints containing the email of the patient using the system Email and the phone number of the patient using the system Phone if stated. In the input either the system Phone or Sms can be used for a phone number, but in the output we use Phone.
Telecom.Extensions A list of extensions containing at most one element containing consent data for the parent Telecom object. Note that this is ignored in the input, but is included when fetching a patient.
`Address Contains a FHIR address with the Country stated, if defined, as the country code for the patient. Note that this is ignored in the input, but is included when fetching a patient.

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

Response code Explanation
200 Ok, success.
400 Bad request, failed FHIR resource validation.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
422 Unprocessable entity, there was an error processing the request.

Error codes

Error Explanation
PatientCreateLanguageCodeNotSupported The language code specified for the patient was not supported for the customer.
PatientCreateInvalidIdentifierSystem Could not find an identifier matching the requested for national identification number.
PatientCreateIgnoredIdentifierSystem An informational note that there existed identifier systems that were ignored by our server. Does not cause an error.
PatientCreateConflictingClientFound This error depends on the customer specific settings for unique national identification number and/or phone number. Given these settings, if there was a patient found conflicting with the input it is not possible to create another.
PatientInvalidPhone / PatientInvalidEmail / PatientCreateInvalidNationalIdentityNumber The phone number/email/national identification number provided failed validation.
PatientPhoneRequired/ PatientEmailRequired / PatientNationalIdentityNumberRequired TThe phone number/email/national identification number was not found.
ContactPointUseNotSupported The only phone/email contact point we could fins had the Use of Old or Temp.
PatientNameRequired Patient name is required but none was found.
PatientNameInvalid Patient name is required but none was found.
PatientCreateLanguageCodeNotSupported Both Given name and Family name needs to be set for the patient’s name but at least one of them were missing.

GET /Patient/{patient_id}

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

Response types

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
404 Not found, patient with id {patient_id} was not found on the customer.

Query Parameters

Parameter Required Description Default Value
patient_id Yes The Visiba Care identifier of the patient. N/A

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

Field name Description
Id The Visiba Care identifier of the healthcare service.
Name The name of the healthcare service in the default language of the customer. This is the same name that is seen in the Visiba Care interface. If no translation is available the result will be <Missing Translation>.

GET /HealthcareService/{healthcareservice_id}

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

Response types

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
404 Healthcare service with id {healthcareservice_id} was not found on the customer.

Query Parameters

Parameter Required Description Default Value
healthcareservice_id Yes The Visiba Care identifier of the healthcare service N/A

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

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
422 Unprocessable entity, there was en error processing the input data.

Input parameters/fields

Parameter/Field Explanation Default
_id Specifies an id of a healthcare service to search for. All other parameters will be igonored if this exists. N/A
skip Defines how many healthcare services of the found healthcare services should be skipped before inserting them in the response bundle. 0
_count Defines how many healthcare services of the found healthcare services should be inserted in the response bundle. Maximum 30. 0

Return body

Field Explanation
Type Is always searchset for this search bundle.
Total Includes the total number of healthcare services that were found given the input parameters.
Link A list of links and their relation to this bundle.
Link.Relation The relation of the link. Currently we only specifiy links defining how to request for the next page for the search set. Is therefor next if it exists.
Link.Url A link that can be used to do an action of the specified relation. For a next-link this can be requested to the API to get the next page.
Entry A list of bundle entries of found appointments.
Entry.FullUrl An API-specific url to the appointment in the entry.
Entry.Resource The appointment for the entry as a GET request would display it.
Entry.Search Search related information.
Entry.Search.Mode Will always be match.

Error codes

Error Explanation
SkipMustBePositive Skip must be >= 0 .
CountMustBePositive Count must be >= 0.

Practitioner

Practitioner resource

A practitioner resource

{
  "resourceType": "Practitioner",
  "id": "[Practitioner id provided by Visiba Care]",
  "identifier": [ -- 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

Field name Description
Id The internal identifier of the practitioner.
Identifier For Swedish customers, includes an Hsa-Id identifier where available.
Name A FHIR HumanName for the practitioner containing Given with the given name, family with the surname, and the Text combining them both.
Telecom Includes email information where available.

GET /Practitioner/{practitioner_id}

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

Response types

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
404 Not found, practitioner with id {practitioner_id} was not found on the customer.

Query Parameters

Parameter Required Description Default Value
practitioner_id Yes The Visiba Care identifier of the practitioner. N/A

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. In this request the healthcare service id is a requirement to specify, and what will be retrieved is therefore all practitioners on the specified healthcare service.

Response type

Response code Explanation
200 Ok, success.
401 Unathorized, missing API key.
403 Forbidden, invalid API key.
422 Unprocessable entity, there was an error processing the request.

Input parameters/fields

Parameter/Field Explanation Default
healthcareServiceId Specifies the healthcare service to search for practitioners at. Required. N/A
_id Specifies an id of an appointment to search for. All other parameters will be igonored if this exists. N/A
skip Defines how many appointments of the found appointments should be skipped before inserting them in the response bundle. 0
_count Defines how many appointments of the found appintments should be inserted in the response bundle. Maximum 30. 0

Return body

Field Explanation
Type Is always searchset for this search bundle.
Total Includes the total number of practitioners that were found given the input parameters.
Link A list of links and their relation to this bundle.
Link.Relation The relation of the link. Currently we only specifiy links defining how to request for the next page for the search set. Is therefor next if it exists.
Link.Url A link that can be used to do an action of the specified relation. For a next-link this can be requested to the API to get the next page.
Entry A list of bundle entries of found practitioners.
Entry.FullUrl An API-specific url to the practitioner in the entry.
Entry.Resource The practitioner for the entry as a GET request would display it.
Entry.Search Search related information.
Entry.Search.Mode Will always be match.

Error codes

Error Explanation
SkipMustBePositive Skip must be >= 0 .
CountMustBePositive Count must be >= 0.
HealthcareServiceIdRequired Search parameter healthcareserviceid was required but not specified.