Exchange data using iCure SDK

At the end of this tutorial, you will be able to use iCure to :

  • Create a patient;

  • Read the previous created patient;

  • Create observations/measures for that patient;

  • Read previous created observations;

Before starting

Before making your first requests, you will need to complete the following steps.

Create your iCure user

Make sure to be registered on the iCure Cloud Manager before going ahead.

Setting up your environment

As soon as you have access to iCure (online or locally), you will need to set up your environment. To do this, you can follow this example which will help you initialize a node application communicating with the iCure solution.

Authenticating with iCure from your code

After completing the steps above, you will be able to dive into writing some code. For this, you will need the encryption private key you downloaded during the registration process of your user.

In the following example, the private key is MIIEvAIBAD...9HOmEwWQ==. Also, do not forget to replace the username - password (esmith - mypassword) by your own values.

Prepare for patient creation
import {
} from '@icure/api'
import {crypto} from '@icure/api/node-compat.js'

const host = '';
const { patientApi, userApi, healthcarePartyApi, cryptoApi } = Api(host, 'esmith', 'mypassword', crypto)

const loggedUser = await userApi.getCurrentUser();
const loggedHcp = await healthcarePartyApi.getCurrentHealthcareParty()

await cryptoApi.loadKeyPairsAsTextInBrowserLocalStorage(
await cryptoApi.checkPrivateKeyValidity(loggedHcp)

Making requests using iCure SDK

Create a patient

Once you are authenticated, you can easily create a patient. The Patient data model is described here.

Create a patient
const patient = await patientApi.createPatientWithUser(loggedUser,
    await patientApi.newInstance(
        new Patient({
            firstName: 'Gustave',
            lastName: 'Eiffel',
            note: 'A very private information'

As you can see in the code above, we are using some specific API methods to create our patient (createPatientWithUser instead of createPatient, api.newInstance instead of "only" creating a new object, ...). This is because those methods are taking care of the data end-to-end encryption for us.

We encourage you to have a look at our secured e2e encryption guidelines in order to know all about them.

Load a patient

After creating a patient, you can find it back using its id :

Load a patient by id
const fetchedPatient = await patientApi.getPatientWithUser(loggedUser,
console.log(JSON.stringify(fetchedPatient, null, ' '))

You can also search a list of patients, corresponding to specific criteria :

Filter patient
const foundPatients = await patientApi.filterByWithUser(loggedUser, new FilterChainPatient({
    filter: new PatientByHcPartyNameContainsFuzzyFilter({
        healthcarePartyId: loggedUser.healthcarePartyId,
        searchString: "eiffel"
console.log( => `${p.firstName} ${p.lastName}°${p.dateOfBirth}`).join('\n'))

Filters offer you a lot of flexibility to search your patients. You can find a few other examples in the following code :

Filter patient with api
const search1 = await patientApi.filterByWithUser(loggedUser, new FilterChainPatient({
    filter: Filter.patient().forHcp(loggedUser.healthcarePartyId)

const search2 = await patientApi.filterByWithUser(loggedUser, new FilterChainPatient({
    filter: Filter.patient().forHcp(loggedUser.healthcarePartyId)

const search3 = await patientApi.filterByWithUser(loggedUser, new FilterChainPatient({
    filter: Filter.patient().forHcp(loggedUser.healthcarePartyId)

const patientFilterBuilder = Filter.patient().forHcp(loggedUser.healthcarePartyId)

const filter =;
const search4 = await patientApi.filterByWithUser(loggedUser, new FilterChainPatient({
    filter: filter

;[search1, search2, search3, search4].forEach((r, idx) =>
    console.log(`Search ${idx+1}\n${ => `${p.firstName} ${p.lastName}°${p.dateOfBirth}`).join('\n')}`)

Add medical data to patient

In iCure, medical data is stored inside contacts. A contact groups a batch of measures/observations (represented in iCure data model as services) in one single transaction. A contact always links together a healthcare party (A care provider) to one patient.

Before adding new medical data into the iCure system, you then absolutely need to create :

  • a patient (See sections Create a patient and Load a patient for more information);

The following code shows you how to create an observation, represented in iCure system as a contact containing a service.

Create a contact with services
const serviceToCreate = await contactApi.service().newInstance(
    new Service({
        valueDate: 20211020,
        status: 0,
        label: 'Hepatitis B virus surface',
        codes: [
            new CodeStub({
                id: '|16935-9|2',
                context: 'code',
                type: '',
                code: '16935-9',
                version: '2',
                label: {
                    en: 'Hepatitis B virus surface Ab [Units/volume] in Serum'
        content: {
            en: new Content({
                measureValue: new Measure({
                    value: 99.0,
                    unit: '[iU]/L',
                    unitCodes: [new CodeStub({
                        id: '|[iU]/L',
                        type: '',
                        code: '[iU]/L'

const contact = await contactApi.createContactWithUser(loggedUser,
    await contactApi.newInstance(
        new Contact({
            responsible: loggedUser.healthcarePartyId,
            services: [serviceToCreate]

Last updated