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:
- search the recipient of the document (healthcare professional or healthcare structure) (required)
- search the sender of the document (the healthcare professional user)(optional)
- search the patient (required) and the encounter (optional)
- proceed to send the medical PDF document(s) to the right healthcare professional or structure (required)
- 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 :
Parameter | Type | Description |
---|---|---|
name | String | family and/or given of the healthcare practitioner. Requires minimum 2 characters This search is based on the beginning of the word. |
identifier | String | RPPS (national identifier of the french healthcare professional). Search on exact value only. |
given | String | firstname of the practitioner. Requires minimum 2 characters This search is based on the beginning of the word. |
family | String | lastname of the practitioner. Requires minimum 2 characters This search is based on the beginning of the word. |
telecom | String | mssante email address. Search on exact value only. |
address | String | postal address of the healthcare professional. This search is based on the beginning of the word and word by word. |
_sort | String | |
_count | int | number of result page on the page (max: 100 ) - 0 not supported |
_id | String |
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": "mail1@mssante.fr",
"use": "work"
},
{
"id": "6673280",
"system": "email",
"value": "mail2@mssante.fr",
"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 :
Parameter | Type | Description |
---|---|---|
name | String | name of the healthcare structure |
identifier | String | FINESS (national identifier of the french healthcare structure) |
telecom | String | mssante email address |
address | String | postal address of the healthcare structure |
part-of | Reference | FHIR Reference of the organization of which this organization forms a part |
_sort | String | |
_count | int | number of result page on the page (max: 100 ) - 0 not supported |
_id | String |
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": "mail1@mssante.fr",
"use": "work"
},
{
"id": "6673280",
"system": "email",
"value": "mail2@mssante.fr",
"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
Field | Sub field | Type | Optional or Always present | Description |
---|---|---|---|---|
id | String | always | Unique identifier in Lifen system | |
name | String | always | Name of the healthcare structure | |
identifier | Array | optional | RPPS (national identifier of the french healthcare professional) or FINESS (national identifier of the french healthcare structure) | |
identifier.system | String | required if the field is present | Could be : - the RPPS ( http://lifen.fr/fhir/Identifier/practitioner-rpps )- the geographic FINESS ( http://finess.sante.gouv.fr/fhir/Identifier/finessEt ) - the legal FINESS (http://finess.sante.gouv.fr/fhir/Identifier/finessJur ) | |
identifier.value | String | required if the field is present | RPPS or FINESS value | |
telecom | Array | optional | MSSante email address | |
telecom.system | String | optional | Telecom type (always email here) | |
telecom.value | String | mandatory if the field is present | Email value | |
telecom.use | String | optional | Purpose of this contact point (always work here) | |
telecom.rank | String | optional | Specified preferred order of use (1 = highest, 2 = medium or nothing) | |
address | Array | optional | Postal address of the healthcare structure | |
address.line | Array[String] | optional | All lines of the address (street, postal code, city, country) | |
address.city | String | optional | City of the address | |
address.postalCode | String | optional | Postal code of the address | |
part-of | Reference | optional | FHIR Reference of the organization of which this organization forms a part |
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
sender
or 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
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.
Error code | Field | Description |
---|---|---|
403 | context | Context FHIR Reference is unauthorized |
403 | subject | Subject FHIR Reference is unauthorized |
404 | subject | Subject FHIR Reference is unknown |
404 | sender | Sender FHIR Reference is unknown |
404 | context | Context FHIR Reference is unknown |
412 | - | You forgot to configure your support email address on developer portal |
412 | recipient | You have to configure a valid mssante email for the recipient telecom (any other type of email address won't work) |
422 | recipient | 10 recipients maximum are authorized |
422 | recipient | At least one recipient is required |
422 | recipient | Unknown email address |
422 | recipient | You can't have two identical recipient in your sending |
422 | recipient | Only Practitioner and Organization type are valid recipients |
422 | sender | Invalid sender |
422 | managing-organization | Invalid managing-organization or you use a token who already has the organization link to your application |
422 | payload | At least one payload is required |
422 | payload | Invalid type : refer to the list Document Type |
422 | payload | At least one payload is required |
422 | subject | Subject is required |
422 | subject/detailedSubject | Subject or detailedSubject is required |
422 | detailedSubject | Missing or invalid fields in patient information |
500 | - | Lifen side error (server side error) |
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": "william.eclancher@lifen.mssante.fr"
}
]
}
},
{
"resource" : {...}
},
]
}
Resource status
Status | Description |
---|---|
preparation | The document has arrived to the Lifen Platform and will be processed soon. |
in-progress | The document is being processed by the Lifen Platform. The status is in-progress until an acknowledgement confirms receipt of the document. |
completed | The document has been processed by the Lifen Platform and an acknowledgement confirms successful receipt. |
entered-in-error | The document has not been sent, there has been an error on Lifen side. |
unknown | The document has not been sent, there has been an error on Lifen side. |
6. How to test ?
Use these recipients examples to test each response status
RPPS Practitioner (recipients :identifier.value ) | Practitioner's email address (recipients :telecom.value ) | Response status to test | Comment |
---|---|---|---|
10100573657 | sandrine.calvel-will@test.lifen.mssante.fr | preparation | All the sendings request get this status in first place before transit to 'in-progress' status |
10100573657 | sandrine.calvel-will@test.lifen.mssante.fr | in-progress | All the sendings request get this status in second place after 'preparation' status |
10004085790 | william.eclancher@medecin.mssante.fr | entered-in-error | |
- | - | unknown | (NOT AVAILABLE IN TEST MODE) |
10100573657 | sandrine.calvel-will@test.lifen.mssante.fr | completed |
Updated 7 months ago