Creating accounts using the API

Who may do it?

  • A healthcare provider using an app session The healthcare provider will have access to all data of the patient that were created by himself
  • An external service The external service will have access according to its access filter.
  • A researcher using an app session that is bound to a research project The new account holder will join the research project that the app is bound to
  • A project analyzer bound to a research project The new account holder will join the research project the analyzer is bound to.
  • An account holder is able to create another account holder account. The creator will be the representative for the newly created account.

How must the request look like?

Here is an example request:

POST /fhir/Patient

{
  "resourceType" : "Patient",
  "active" : true,
  "name" : [ {
     "family" : "Lastname",
     "given" : ["Firstname"]
   }],
  "telecom" : [ {
     "system" : "email",
     "value" : "*email@domain.de"
   }, {
     "system" : "phone",
     "value" : "*01234567*"
   }
   ],
  "gender" : "male",
  "birthDate" : "1973-12-31",
  "address" : [{
     "line" : ["Examplestreet 1"],
     "city" : "Examplecity",
     "postalCode" : "12345",
     "country" : "CH"
   }],
  "communication" : [{
    "language" : {
       "coding" : { 
           "code" : "en", 
           "system" : "urn:ietf:bcp:47" 
       }
    },
    "preferred" : true
   }],
  "extension" : [
    {
      "url" : "http://midata.coop/extensions/account-password",
      "valueString" : "abc123"
    },
    {
      "url" : "http://midata.coop/extensions/terms-agreed",
      "valueString" : "midata-terms-of-use--1.0"
    },
    {
      "url" : "http://midata.coop/extensions/terms-agreed",
      "valueString" : "midata-privacy-policy--1.0"
    }
  ]
}
  • First name and last name must be given
  • email address is optional : if none is set user cannot log in. If no email is provided do not include system / value pair into telecom array
  • phone number is optional. If no phone number is provided do not include system / value pair into telecom array
  • address is optional, but either email or address MUST be given.
  • communication.language.coding sets the default language for communication.
  • Extension http://midata.coop/extensions/account-password allows to set an initial account password. Support for this extension may be dropped or use may be restricted in the future. If no password is set user will be asked to choose his/her own password when clicking on the email validation email link.
  • Extension http://midata.coop/extensions/terms-agreed is needed to mark terms and conditions as signed. Passed values must be corrected when a new version of the terms and conditions is uploaded.
  • Extension http://midata.coop/extensions/join-project can be used to add a new member to a research project. If the current session is a OAuth researcher session it will have a research project context, In that case the new user will be automatically added to the current research project. The same applies if a project analyzer is used.

Example to join a research project upon registration

{ 
   "extension" : [
    { 
       "url" : "http://midata.coop/extensions/join-project",
       "valueCoding" : { 
           "system" : "http://midata.coop/codesystems/project-code",
           "code" : "ABCD-1234"
       }
    }

   ]
}

Existing accounts vs new accounts

When a patient resource is posted the platform checks for an existing account with matching demographic data:

  • The primary key for the new account is the email address of the new user. Is there already an account with this email?
  • Is there an account with the same name, birthdate and address?

These are these possible cases:

  • New user:

There is no matching account A new MIDATA account is created and the caller has immediate write access.

  • Existing user:

There is a matching account that was created by the user itself or by another practitioner/researcher. No new account is created, the existing account is reused.

If the API call is made by an external service or project analyzer with the “preconfirmation” option enabled in the application settings: A consent that allows to only write and read back new data is created.

Otherwise an unconfirmed consent is created instead that the target user must confirm before the caller may access that account.

  • Existing user, created by the same caller (and project context if caller is researcher)

The caller himself created the account earlier. No account and no consent will be created. A resource exists error will be thrown

Notifying the user of the account to be created

A new user should be notified, that an account has been created for him and eventually that he needs to set a password. Define a message of type “Registration of a new user by someone else” for the application that does the account creation. Clicking on the “confirm-url” link that may be used as email variable will take the account holder to the password change screen.

An existing user should be notified, that he needs to confirm the consent. Define a message of type “Proposed consent (Grantor, Account Holder)” for the application that does the account creation. Clicking on the “confirm-url” link that may be used as email variable will take the account holder to the login screen, afterwards he will be directly taken to the consent that needs confirmation.

Notifying the account creating software

The API call will return the Patient resource as result. The caller software should store the “id” field of the patient returned. For a new account the calling software may start to work with the account immediately. For an existing account the returned resource has an FHIR extension like this:

"extension": [
    {
      "url": "http://midata.coop/extensions/service-url",
      "valueUri": "https://localhost/#/public/service?consent=5b226796f723ac28b&login=demo@domain.com"
    }
]

The caller may add the returned link to his web frontend. The account holder can click on the link, log in and confirm the consent.

The “service” frontend (currently baseurl/#/public/service ) may be used by the account holder to confirm required consents. When this is required the account creation request will return the URL in the http://midata.coop/extensions/service-url FHIR extension as described above. A full description of the service portal features can be found at the Links to the portal page

Push Notifications

The calling application can be notified about changes of the user consent by using the FHIR subscription mechanism. A single entry in the subscription table will be sufficient to capture all changes.

The details still need to be specified.