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 :
| 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",
"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 :
| 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",
"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 :
| Parameter | Type | Description |
|---|---|---|
subject | Reference | patient subject of your document |
context (optional) | Reference | encounter's patient |
recipients | Reference | all the recipients, with their mssante email addresses |
payload | base64 | all documents, in base64 format |
type | Code | for each document, you must choose the type of the document referring to the list Document Type |
content | Code | for 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-urlfield is usable directly to call our API and get the delivery status of your sending
| 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 | context | Context FHIR Reference is unknown |
412 | - | You forgot to configure your support email address on developer portal |
412 | recipient | You have to configure valid mssante email for the recipient telecom and not any other type of address |
422 | recipient | 10 recipients maximum are authorized |
422 | recipient | At least one recipient is required |
422 | recipient | Invalid recipient |
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 | 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 |
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
| 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 |
completed | The document has been processed by the Lifen Platform |
entered-in-error | The document has not been sent, there has been an error on Lifen side and you can see the associated reason of the failure |
Updated 3 days ago