Send a document to Healthcare Professionals

Introduction

This API allows you to securely send medical documents to any french healthcare professional or any french healthcare structure via the MS Santé standard.

MS Santé is a secure messaging protocol use in France. MS Santé offered a confidente space to exchange medical data to any healthcare professional or structure in dematerialized way. Today, around 60% of the healthcare professional have an MS Santé address and more than 2000 healthcare structure too.

Using this protocol is required to be compliant with the remote monitoring applications referential and obtain reimbursements from the government.

For more details please refer to this document

📘

Lifen is an MSSanté operator in France, certified by the ANS - a french institution to bring healthcare into the digital era.

Access Control

You need a Machine To Machine Communications to use this API.

You need to have the SEND_TO_MSS scope to access the Platform service.

Sending medical document workflow

Sending medical document(s) to healthcare professionals or structures via our API is a 4-step process :

  • first you need to search the patient reference of the patient concerned by the document(s)
  • then you need to search the recipient MS Santé email from our national directory of healthcare professionals and healthcare structures
  • then you can proceed to send the medical PDF document(s) to the right healthcare professional or structure
  • finally, you can track the mail delivery status

1. Search the patient

First, please search the patient concerned by the document(s) by using the Access Patient Information Platform Service.

Once you've found the right patient, you need to keep the FHIR id of your patient for step 3.

Then, you can search the encounter concerned by the document(s) by using the Access Encounter Information Platform Service. This step is optional.

Once you've found the right encounter, you need to keep the FHIR id of your encounter for step 3 too.

2. Search the recipient

Then, search the recipient by using the Directory API. You can search healthcare professionals or healthcare structures.

📘

You can only search 100 healthcare professional or structure per request (no paginated search available). If you find more than 100 results, please add more search parameters to reduce the number of results.

Please use this route to search healthcare professionals :

POST api.lifen.fr/fhir/v3/Practitioner/$search-for-mss

You can search on these following parameters :

ParameterTypeDescription
nameStringfamily and/or given of the healthcare practitioner.
Requires minimum 2 characters
This search is based on the beginning of the word.
identifierStringRPPS (national identifier of the french healthcare professional). Search on exact value only.
givenStringfirstname of the practitioner.
Requires minimum 2 characters
This search is based on the beginning of the word.
familyStringlastname of the practitioner.
Requires minimum 2 characters
This search is based on the beginning of the word.
telecomStringmssante email address. Search on exact value only.
addressStringpostal address of the healthcare professional. This search is based on the beginning of the word and word by word.
_sortString
_countintnumber of result page on the page (max: 100) - 0 not supported
_idString

Response :

{
    "resourceType": "Bundle",
    "id": "aff6fcd5-76fb-40eb-bfb0-64fde9a0678c",
    "meta": {
        "lastUpdated": "2022-10-11T10:05:08.896+00:00"
    },
    "type": "searchset",
    "total": 451247,
    "entry": [
        {
            "fullUrl": "https://api.lifen.fr/fhir/dstu3/Practitioner/[id]",
            "resource": {
                "resourceType": "Practitioner",
                "id": "[id]",
                "identifier": [
                    {
                        "system": "urn:oid:1.2.250.1.71.4.2.1",
                        "value": "811111111111111"
                    }
                ],
                "active": true,
                "name": [
                    {
                        "use": "official",
                        "family": "Michue",
                        "given": [
                            "Paulette"
                        ],
                        "prefix": [
                            "DR"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "id": "6673280",
                        "system": "email",
                        "value": "[email protected]",
                        "use": "work"
                    },
                    {
                        "id": "6673280",
                        "system": "email",
                        "value": "[email protected]",
                        "use": "work",
                        "rank": 1 
                    }
                ],
                "address": [
                    {
                        "id": "42941332",
                        "use": "work",
                        "line": [
                            "CLINIQUE TEST",
                            "71 RUE TEST",
                            "12345 ST TEST CEDEX"
                        ],
                        "city": "TEST",
                        "postalCode": "12345",
                        "country": "FRA"
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        }
]}

Please use this route to search healthcare structures :

POST api.lifen.fr/fhir/v3/Organization/$search-for-mss

You can search on these following parameters :

ParameterTypeDescription
nameStringname of the healthcare structure
identifierStringFINESS (national identifier of the french healthcare structure)
telecomStringmssante email address
addressStringpostal address of the healthcare structure
part-ofReferenceFHIR Reference of the organization of which this organization forms a part
_sortString
_countintnumber of result page on the page (max: 100) - 0 not supported
_idString

Response :

{
    "resourceType": "Bundle",
    "id": "aff6fcd5-76fb-40eb-bfb0-64fde9a0678c",
    "meta": {
        "lastUpdated": "2022-10-11T10:05:08.896+00:00"
    },
    "type": "searchset",
    "total": 451247,
    "entry": [
    {
      "fullUrl": "https://api.lifen.fr/fhir/dstu3/Organization/[id]",
      "resource": {
        "resourceType": "Organization",
        "id": "996644",
        "name": "CH TEST",
        "telecom": [
          {
            "id": "6673280",
            "system": "email",
            "value": "[email protected]",
            "use": "work"
          },
          {
            "id": "6673280",
            "system": "email",
            "value": "[email protected]",
            "use": "work",
            "rank": 1 
          }
        ],
        "address": [
          {
            "id": "3157415241441669992",
            "line": [
              "CH TEST",
              "124 Rue TEST",
              "75000 Paris"
            ],
            "city": "Paris",
            "postalCode": "75000"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
]}

Once you've found your recipient(s), keep all the FHIR ids you need for the next step.

3. Send your medical document

In this step, you'll proceed to sending a medical document and you'll use all the references you've kept in the previous steps.

🚧

Don't forget to declare your support email address in our developer portal (link available in the top menu)

Please use the following route :

POST api.lifen.fr/fhir/v3/CommunicationRequest/$send-to-mss

You need to complete the following information :

ParameterTypeDescription
subjectReferencepatient subject of your document
context (optional)Referenceencounter's patient
recipientsReferenceall the recipients, with their mssante email addresses
payloadbase64all documents, in base64 format
typeCodefor each document, you must choose the type of the document referring to the list Document Type
contentCodefor each document, you must describe the content-type of the document application/pdf

Example of the body request

{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"payload",
         "part":[
            {
              "name":"document",
              "resource": {
                "ressourceType":"DocumentReference",
                "type":{
                  "coding":[{
                    "system":"urn:oid:2.16.840.1.113883.6.1",
                    "code":"11488-4"
                  }]
                },
                "content":[{
                  "attachment":{
                    "content-type":"application/pdf",
                    "data":"{{document in base 64}}"
                  }
                }]
              }
                        }
         ]
      },
      {
         "name":"recipients",
         "part":[
            {
               "name":"recipient",
               "resource":{
                  "resourceType":"Practitioner",
                  "id":"456",
                  "telecom":[
                     {
                        "id":"42995", // optional
                        "system":"email",
                        "value":"[email protected]"
                     },
                  ]
               }
            }
         ]
      },
      {
         "name":"subject",
         "valueReference":{
           "reference": "Patient/456"
         }
      },
     {
         "name":"context",
         "valueReference":{
           "reference": "Encounter/5555"
         }
      }
   ]
}

Response :

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "tracking-url",
            "valueString": "https://api.lifen.fr/fhir/v3/CommunicationRequest/$tracking?transaction-id=ifad1343e-496f-11ed-b878-0242ac120002"
        },
        {
            "name": "transaction-id",
            "valueString": "fad1343e-496f-11ed-b878-0242ac120002"
        }
    ]
}

📘

The url available in the tracking-url field is usable directly to call our API and get the delivery status of your sending

Error codeFieldDescription
403contextContext FHIR Reference is unauthorized
403subjectSubject FHIR Reference is unauthorized
404subjectSubject FHIR Reference is unknown
404contextContext FHIR Reference is unknown
412-You forgot to configure your support email address on developer portal
412recipientYou have to configure valid mssante email for the recipient telecom and not any other type of address
422recipient10 recipients maximum are authorized
422recipientAt least one recipient is required
422recipientInvalid recipient
422recipientUnknown email address
422recipientYou can't have two identical recipient in your sending
422recipientOnly Practitioner and Organization type are valid recipients
422payloadAt least one payload is required
422payloadInvalid type : refer to the list Document Type
422payloadAt least one payload is required
422subjectSubject is required
500-Lifen side error (server side error)

4. Check the delivery status

After you've sent the medical document(s), Lifen processes it. This process can take up to 5 minutes. After this delay, you can follow the delivery status through the following endpoint :

GET  https://api.lifen.fr/fhir/v3/CommunicationRequest/$tracking?transaction-id=ifad1343e-496f-11ed-b878-0242ac120002

🚧

After two month, the delivery status will no longer be available

Response

{
    "resourceType": "Bundle",
        "type": "collection",
    "total": 2,
      "entry": [
    {
      "resource" : {
                "resourceType": "Communication",
                "status": "completed", // see status code available below
                "sent": "2019-03-07T13:07:23.000+00:00", // only if status = completed
                "medium": [
                {
                  "coding": [
                    {
                      "system": "http://lifen.fr/fhir/ValueSet/communication-medium",
                      "code": "MSSANTE",
                      "display": "[email protected]"
                    }
                  ]
                }
              ]
            }
    },
        {
      "resource" : {...}
    },
  ]
}

Resource status

StatusDescription
preparationThe document has arrived to the Lifen Platform and will be processed soon
in-progressThe document is being processed by the Lifen Platform
completedThe document has been processed by the Lifen Platform
entered-in-errorThe document has not been sent, there has been an error on Lifen side and you can see the associated reason of the failure