Skip to main content

Endpoint parameters

In order to simplify the integration process for technical teams, we have developed a set of helper endpoints that streamline access to relevant data. These endpoints provide quick and efficient retrieval of the information needed to bridge and facilitate interaction between the diagnostic-support and severity-assessment endpoints, minimizing the amount of additional code required from the integrator.

Body sites endpoint

This helper endpoint returns a standardized list of body site codes used to specify the location of a pathology on the human body. These codes are essential for accurately defining the affected area when interacting with the diagnostic-support endpoint.

https://medical-device-params.legit.health/v2.0/body-sites

Clinical signs endpoint

This auxiliary endpoint provides a standardized list of clinical signs, including multilingual translations of the visual sign keys returned by the severity-measurement endpoint.

https://medical-device-params.legit.health/v2.0/clinical-signs

Questionnaires endpoint

Each pathology or condition may be associated with none, one, or multiple scoring systems. These scoring systems can either be calculated automatically through AI model analysis of the image, or, in some cases, may require responses to specific questions from the patient or doctor. The severity-assessment endpoint, detailed in the section Endpoint specification, triggers the calculation of these scoring systems.

This endpoint helps to:

  • Identify if any scoring systems are associated with a particular pathology or condition, and if so, provide the details of the scoring system.

  • In cases where a scoring system is associated, if questionnaires are involved, the endpoint also provides the necessary information related to the questions, including the content of the questions and the available answer options.

By providing the pathology query parameter with an ICD-11 code (e.g., EA90 for Psoriasis), users can obtain relevant scoring systems and questionnaires tailored to the pathology or condition.

Example:

https://medical-device-params.legit.health/v2.0/questionnaires?pathology=EA90

Request

https://medical-device-params.legit.health/v2.0/questionnaires?pathology=EA90

Request parameters

  • pathology (required): The ICD-11 code representing the specific pathology for which the questionnaire is needed. For example, EA90 represents Psoriasis.
Info

This ICD-11 code will be returned by the diagnostic-support endpoint. Refer to the Endpoints specification section for further details on how to retrieve pathology/condition codes.

Response

The API responds with a JSON object containing one or more questionnaires pertinent to the specified pathology. These questionnaires are designed to gather standardized information that assists in the assessment and monitoring of the condition.

Relevant keys in the body of the response
[
{
"identifier": "apasiLocal",
"code": "apasi",
"mode": "local",
"path": "/severity-assessment/image-based/local",
"title": {
"en_GB": "Local automatic psoriasis area and severity index",
"es_ES": "Índice automático de gravedad y área de psoriasis local"
},
"description": {
"en_GB": "Clinical tool for a precise psoriasis severity assessment",
"es_ES": "Herramienta clínica para determinar la gravedad de la psoriasis"
},
"questionnaire": [
{
"code": "surface",
"name": {
"en_GB": "Affected area",
"es_ES": "Área afectada"
},
"description": {
"en_GB": "This value corresponds to the percentage of involvement of the specific area of the body you are reporting",
"es_ES": "Este valor corresponde al porcentaje de afectación de la zona concreta del cuerpo que estás reportando"
},
"input": {
"type": "number",
"min": 0,
"max": 100
}
}
]
},
{
"identifier": "pure4",
"code": "pure4",
"mode": "global",
"path": "/severity-assessment/text-based",
"title": {
"en_GB": "Psoriatic arthritis UnclutteRed screening Evaluation",
"es_ES": "Cuestionario de evaluación de la artritis psoriásica"
},
"description": {
"en_GB": "The aim of this questionnaire is to do an screening of psoriatic arthritis",
"es_ES": "El propósito de este cuestionario es realizar un cribado de pacientes con artritis psoriásica"
},
"questionnaire": [
{
"code": "question1",
"name": {
"en_GB": "Have you ever had a globally swollen and painful finger or toe?",
"es_ES": "¿Ha tenido alguna vez dolor e hinchazón/inflamación que afectara a todo un dedo de la mano o del pie?"
},
"description": { "en_GB": "", "es_ES": "" },
"input": {
"type": "select",
"options": [
{ "label": { "en_GB": "No", "es_ES": "No" }, "value": "0" },
{ "label": { "en_GB": "Yes", "es_ES": "Sí" }, "value": "1" }
]
}
},
{
"code": "question2",
"name": {
"en_GB": "Have you ever had heel pain as soon as you stand up in the morning?",
"es_ES": "¿Ha tenido o notado alguna vez dolor en el talón al ponerse de pie por la mañana?"
},
"description": { "en_GB": "", "es_ES": "" },
"input": {
"type": "select",
"options": [
{ "label": { "en_GB": "No", "es_ES": "No" }, "value": "0" },
{ "label": { "en_GB": "Yes", "es_ES": "Sí" }, "value": "1" }
]
}
},
{
"code": "question3",
"name": {
"en_GB": "Have you ever had left and right buttock pain, at the same time or not?",
"es_ES": "¿Ha tenido alguna vez dolor en el glúteo derecho o izquierdo, al mismo tiempo o por separado?"
},
"description": { "en_GB": "", "es_ES": "" },
"input": {
"type": "select",
"options": [
{ "label": { "en_GB": "No", "es_ES": "No" }, "value": "0" },
{ "label": { "en_GB": "Yes", "es_ES": "Sí" }, "value": "1" }
]
}
},
{
"code": "question4",
"name": {
"en_GB": "Have you ever had a swollen and painful joint? (hands, feet, knees, or ankles, for example)",
"es_ES": "¿Ha tenido alguna vez hinchazón y dolor en una articulación (manos, pies, rodillas o tobillos, por ejemplo)?"
},
"description": { "en_GB": "", "es_ES": "" },
"input": {
"type": "select",
"options": [
{ "label": { "en_GB": "No", "es_ES": "No" }, "value": "0" },
{ "label": { "en_GB": "Yes", "es_ES": "Sí" }, "value": "1" }
]
}
}
]
}
]

Response cheatsheet

Remember, if your goal is to use this information to query the severity-assessment endpoint, here are the keys you need to focus on and use:

  1. code

    • What it is: The code represents the short identifier for the scoring system.
    • Why it's important: This will be the key you need to invoke within the body of your request under the scoring systems object.
  2. path

    • What it is: The path indicates the endpoint URL that should be invoked in the subsequent steps.
    • Why it's important: This will guide you to the correct URL for querying the severity assessment information.
  3. questionnaire and code for questions

    • What it is: The questionnaire contains an array of questions, each with a unique code.
    • Why it's important: Each code in the questionnaire is the unique identifier for the question. These are the values you need to send in your request, as they represent the answers to the specific questions.
Tip

Use this cheatsheet as a quick reference to understand which keys are important for making correct requests to the diagnostic-assessment endpoint.

Response details long version

Description of the most relevant keys in the body of the response:

  • identifier

    • Description: A unique identifier for each possible local or global scoring system. It is used to help the integrator understand the results but is not required for any endpoint requests.
    • Example: "apasiLocal", "pure4"
  • code

    • Description: Represents the short identifier for the scoring system. This will be the key you need to invoke within the body of your request to severity-assessmentendpoint under the scoring systems object.
    • Example: "apasi", "pure4"
  • mode

    • Description: Specifies whether the assessment is for local or global use.
    • Values: "local" (for local areas of the body), "global" (for the whole body or multiple regions).
    • Example: "local", "global"
  • path

    • Description: indicates the endpoint URL that should be invoked in the subsequent steps.
    • Example: "/severity-assessment/image-based/local", "/severity-assessment/text-based"
  • title

    • Description: The title of the assessment tool in different languages. This key contains an object with language codes as keys and the translated title as values.
    • Example:
      {
      "en_GB": "Local automatic psoriasis area and severity index",
      "es_ES": "Índice automático de gravedad y área de psoriasis local"
      }
  • description

    • Description: A short description of the tool in different languages. Similar to title, it contains translations for different languages.
    • Example:
      {
      "en_GB": "Clinical tool for a precise psoriasis severity assessment",
      "es_ES": "Herramienta clínica para determinar la gravedad de la psoriasis"
      }
  • questionnaire

    • Description: An array of questions included in the assessment tool. Each question object contains various keys to define the question and its input type.
    • Example:
      [
      {
      "code": "surface",
      "name": {
      "en_GB": "Affected area",
      "es_ES": "Área afectada"
      },
      "description": {
      "en_GB": "This value corresponds to the percentage of involvement of the specific area of the body you are reporting",
      "es_ES": "Este valor corresponde al porcentaje de afectación de la zona concreta del cuerpo que estás reportando"
      },
      "input": {
      "type": "number",
      "min": 0,
      "max": 100
      }
      }
      ]

    Inside each question:

    • code: A unique identifier for the question.
    • name: The question text in multiple languages (language codes as keys).
    • description: Additional information or clarification about the question (also in multiple languages).
    • input: Defines the input type and constraints for the question. This can include:
      • type: The input type (e.g., "number", "select").
      • min/max: The minimum and maximum values for numeric input (if applicable).
      • options: An array of possible options for a select input (for example, Yes/No options).

Observations

Note

This endpoint belongs to version v2.0 of the API. Make sure you are using the correct version in your requests, as future versions may introduce changes to the structure or behavior of this endpoint.