Call Example

This section details all the steps required to obtain personalized vaccination recommendations for a patient.

The usage context is as follows:

  • The end user, a health professional, has opened a patient record in their business software.
  • The health professional wants to obtain personalized vaccination recommendations for this patient.

Before reading the steps below, we recommend trying Mentor, the SADV reference interface. It is publicly accessible through a web browser, with no account creation or authentication required. It is used to demonstrate and evaluate the expected user journey and integration best practices, in a workflow close to that of business software.

The steps for obtaining vaccination recommendations are:

  1. Retrieve the patient’s basic information.
  2. Retrieve the health profile questionnaire.
  3. Fill out the health profile questionnaire.
  4. Build the patient record to send.
  5. Retrieve the vaccination recommendations.
  6. Display the vaccination recommendations.

Steps 1 and 2 are optional. Their purpose is to retrieve additional information about the patient, which will make it possible to refine the vaccination recommendations. This additional information makes up the patient’s health profile.

We assume here that you already have access to NUVA to encode the patient’s vaccination history, as well as access to the VaccinationProfile (PHP library) library.

Step 1: Retrieve Basic Information

We assume that the health professional’s business software has already retrieved the following basic information: the patient’s date of birth, sex, and optionally their area of residence postal code.

Step 2: Retrieve the Health Profile Questionnaire

To retrieve the health profile questionnaire, the client software must send an HTTP POST request to the /questionnaire URL of the SADV API.

For example, for a male patient born on January 1, 2000, the request is as follows (the postal code is not specified):

# parameter varies depending on the environment
SADV_ROOT_URL=https://api.fr.sad.mesvaccins.net
ACCESS_TOKEN=...

# patient information
BIRTHDATE="2000-01-01"
GENDER="m"

curl -X POST "${SADV_ROOT_URL}/questionnaire" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "patient": {
    "birthdate": "'"${BIRTHDATE}"'",
    "gender": "'"${GENDER}"'"
  },
  "requested_by_professional": true
}'

For more details about this request, you can consult the REST endpoint documentation.

Step 3: Fill Out the Health Profile Questionnaire

The previous endpoint returns, as a tree, the hierarchical questions of the health profile questionnaire.

Each node in the tree is a section containing a title and a list of conditions to be entered by the user.

For each condition, its type (boolean, choice list, date, etc.) and its label are specified.

The client software must display the tree questionnaire to the user, and collect their answers. The collected information makes up the health profile. The client software may persist this information to avoid asking the user for it every time.

To implement the health profile questionnaire interface, we suggest following the behavior of the health questionnaire in our Mentor tool, the publicly accessible reference interface without authentication.

Here is an example questionnaire response:

[
  {
    "alert": {},
    "description": {},
    "help": {},
    "question": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "title": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "id": "c396ad68-b41a-4712-9627-655de08541a2",
    "sections": [
      {
        "alert": {},
        "description": {},
        "help": {},
        "question": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "title": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "id": "4c39da47-6db7-41ee-84a5-6ecdd2144703",
        "sections": [],
        "conditions": [
          {
            "id": "ba606ef4-9ebb-41b2-a81f-56a36bf8897e",
            "label": {
              "en": "IDR (mm)",
              "fr": "IDR (mm)"
            },
            "condition_type": "integer",
            "position": 1
          }
        ]
      }
    ],
    "conditions": []
  }
]

A questionnaire is composed of sections that are themselves composed of sections or conditions. A section can contain only other sections or conditions, but never both.

Here is the breakdown of a Section object:

  • alert: an alert with translations in different languages.
  • description: a description with translations in different languages.
  • help: help text with translations in different languages.
  • question: a question with translations in different languages.
  • title: a title with translations in different languages.
  • id: the section identifier.
  • sections: an array of subsections.
  • conditions: an array of conditions.

Here is the breakdown of a Condition object:

  • id: condition identifier.
  • label: condition label in different languages.
  • condition_type: condition type (boolean, integer, date, float).
  • help: help or description of the condition in different languages.
  • position: position of the condition in the section.

Step 4: Build the Patient Record to Send

The client software must build a patient record to send to the SADV API. This patient record is a JSON object containing:

  • the patient’s basic information (date of birth, sex, area of residence postal code);
  • the patient’s health profile (optional information);
  • the vaccination history.

Here is the list of possible parameters:

  • patient:
    • birthdate: patient’s date of birth in YYYY-MM-DD format.
    • gender: patient sex. Possible values are m for male and f for female.
    • prevention_acts: array representing the list of the patient’s vaccination acts. If the patient has none, send an empty array.
    • conditions: optional list of patient health profile items corresponding to the completed questionnaire.
    • area_of_residency: optional patient area of residence.
    • birthplace: optional patient place of birth.
  • requested_by_professional: boolean indicating whether the request is made by a professional.

Here is an example patient record for a male born on January 30, 1988, in France, living in Bordeaux, and having received a Boostrixtetra vaccine on January 1, 2019:

{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9",
        "booster": false
      }
    ],
    "conditions": [
      {
        "id": "3e76320a-0b4d-4cb2-8095-764b19b08017",
        "value": true
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}

Step 5: Retrieve Vaccination Recommendations

Vaccination recommendations are retrieved by sending an HTTP POST request to the /diagnostic_for_patient URL of the SADV API.

# parameter varies depending on the environment
SADV_ROOT_URL=https://api.fr.sad.mesvaccins.net
ACCESS_TOKEN=...

curl -X POST "${SADV_ROOT_URL}/diagnostic_for_patient" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9",
        "booster": false
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}'

The response to the request is a JSON object containing the vaccination recommendations for the patient.

Step 6: Display Vaccination Recommendations

The client software must display the vaccination recommendations to the health professional. The graphical rendering of vaccination recommendations is left to the client software’s discretion.

The JSON object returned by the SADV API contains:

  • a global conclusion on the patient’s vaccination status;
  • a list of vaccination recommendations, grouped by disease.

Possible global conclusions include:

  • no_action: no action required.
  • up_to_date: no action required, the patient is up to date on vaccinations.
  • late: action overdue.
  • todo: action to be done soon.
  • unmanaged: unmanaged case, but data is available.
  • suggested: suggested action, but not mandatory.
  • exception: unmanaged case.
  • contraindicated: action not recommended.

The disease-level detail includes the target disease and the number of preventive acts performed. The advice field contains all messages related to the disease, with a conclusion indicating the status for this disease. targeted_date indicates when the vaccine should be administered, and limit_date indicates the latest recommended date.

The messages field contains additional guidance that can be displayed to health professionals or patients. The documents field contains files describing the official recommendations associated with the disease. The matching_conditions field contains the conditions that affected the result.

Next Step

See the OpenAPI specification for the endpoints, JSON schemas, and error statuses.