Send a medical document to Healthcare Professionals via MS Santé

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 used in France. MS Santé offers a secure space to exchange medical data with any healthcare professional or structure in dematerialized way. Today, around 60% of French healthcare professionals and more than 2000 healthcare structures have at least one MS Santé address.

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

📘

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

Access Control and Configuration

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.

🚧

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

Workflow

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

1. search the recipient of the document (healthcare professional or healthcare structure) (required)
2. search the sender of the document (the healthcare professional user)(optional)
3. search the patient (required) and the encounter (optional)
4. proceed to send the medical PDF document(s) to the right healthcare professional or structure (required)
5. track the mail delivery status

1. Search the recipient

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

🚧

You are limited to 10 recipients maximum by sending. You are also limited to 10 documents by sending.

📘

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

Search healthcare professional

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 :

Response :

{
	"resourceType": "Bundle",
	"id": "aff6fcd5-76fb-40eb-bfb0-64fde9a0678c",
	"type": "searchset",
	"total": 451247,
	"entry": [
		{
			"fullUrl": "https://api.lifen.fr/fhir/dstu3/Practitioner/[id]",
			"resource": {
				"resourceType": "Practitioner",
				"id": "[id]",
				"identifier": [
          {
            "system": "http://lifen.fr/fhir/Identifier/practitioner-rpps",
            "value": "11111111111"
          }
        ],
				"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"
			}
		}
]}

Search healthcare structure

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 :

Response :

{
	"resourceType": "Bundle",
	"id": "aff6fcd5-76fb-40eb-bfb0-64fde9a0678c",
	"type": "searchset",
	"total": 451247,
	"entry": [
    {
      "fullUrl": "https://api.lifen.fr/fhir/dstu3/Organization/[id]",
      "resource": {
        "resourceType": "Organization",
        "id": "996644",
        "name": "CH TEST",
        "identifier": [
          {
            "system": "http://finess.sante.gouv.fr/fhir/Identifier/finessEt",
            "value": "xxxxxxxx"
          },
          {
            "system": "http://finess.sante.gouv.fr/fhir/Identifier/finessJur",
            "value": "xxxxxxxx"
          }
        ],
        "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"
      }
    }
]}

Presence of response fields

Choose the right recipient email address

Once you've found your recipient(s), keep all the FHIR ids or identifier (RPPS/Finess) you need for the next step. Also, choose the mssanté address you want to. To do that, you can use the rank information (this information may not be present). If the rank is equal to 1, it means that it is his preference for receiving documents. Else, you may just choose first on the list.

2. Search the sender (optional)

Then, you can search the sender of the document in our healthcare professional directory and keep the FHIR id or the RPPS. This practitioner will be mentioned as the author and the legal Authenticator in the CDA file generated when we send the document via MS Santé.

To find the sender of the document, you can search on the api.lifen.fr/fhir/v3/Practitioner/$search-for-mss endpoint as explained in the previous step.

🚧

This information is optional to send your document through MSSanté but this information is required if you want to send your document with an XDM file with CDA.

✅

In order for us to be able to generate a XDM file (with CDA), you need to include a senderor asender-identifier.

Otherwise, we will only send a PDF. Some hospitals strictly require CDA files because it enables a better integration with their existing systems.

3. Search the patient and encounter

In order to send a document, you need to tell us which patient this document is about. The patient can come from 2 different contexts :

• Case 1 : With Patient Information API
  • You want to retrieve from the PAS of the healthcare structure the patient concerned by the document you need to send. To do so, you need to use the Patient/Encounter API Service.
  • Lifen gets the right identifier (INSq, IPP) on the PAS patient for you and adds it in the CDA R2 N1 file generated to send the document.
• Case 2 : Without Patient Information API
  • You prefer to use a patient from your own database
  • You need to send all the patient information (name, birthdate, …) with the strongest identifier you have (INSq, IPP, other)
  • Lifen gets these information and adds them in the CDA R2 N1 file

4. Send the medical document(s)

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.

Please use the following route :

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

• Send document with Patient Information API
• Send document without Patient Information API

📘

If the healthcare structure you are connected to has authorized to add the patient's datamatrix (and if the patient's INS is qualified), then Lifen adds a cover page with the patient's datamatrix after the other pages of the document(s) you're sending.

What does a datamatrix look like ?

Example of MSSanté mail sent by Lifen :

Link example of the XDM file generated (CDA)

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 can be used to get the delivery status of the document(s) you've sent.

5. 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 months, 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"
			        },
			      ],
            "text": "[email protected]"
			    }
			  ]
			}
    },
		{
      "resource" : {...}
    },
  ]
}

Resource status

6. How to test ?

Use these recipients examples to test each response status