Skip to main content

Getting started

This document provides an introductory guide for integrating the Legit.Health AI models using the JSON API. This guide is intended to help your teams prepare for the implementation before consulting the detailed API documentation.

Legit.Health​

info

Legit.Health is a cloud‑based medical device for dermatology that uses clinically validated AI models to analyse skin images and structured clinical information.

Main Features​

  • Triage and prioritise better

    • See which cases are high‑risk or potentially malignant.
    • Decide who needs urgent/high priority referral and assign a clear priority level.

  • Support diagnosis and clinical reasoning

    • Use a ranked list of likely conditions with probabilities to enrich the clinical assessment.
    • Understand whether there is a relevant lesion, and if it is pigmented or non‑pigmented, in a consistent way.

  • Monitor disease and treatments over time

    • Rely on standard severity scores (from images and/or validated questionnaires) to follow disease evolution.
    • Track the patient's progress over time and monitor how their condition evolves with treatment.

  • Improve image-based care

    • Use image quality feedback to know when an image is clinically usable.
    • Make remote and patient‑captured images more reliable for decision‑making.
Role in clinical practice

The AI is a decision-support tool, not an autonomous diagnostic system. All outputs must be reviewed and interpreted by a qualified healthcare professional, together with the full clinical context of the patient.

How to get access?​

To access the protected endpoints of the Legit.Health Medical Device API, you must first obtain your login credentials (email and password) and then use them to generate a time-limited access token.

  1. Contact the Legit.Health customer support team to start your API access request.
  2. The customer support team will guide you through providing the required information.
  3. Once the setup process is complete, you will receive an email at your provided address containing:
    • Your username (the email you provided).
    • A system-generated password.
    • The base URL for accessing the Legit.Health API endpoints.

Endpoints Overview​

Endpoint Request Examples​

URL Convention

Throughout this documentation, we'll use {base_url} to reference the base URL and version of the API. For example: {base_url}/login means https://api.legit.health/version/login

Login​

The login endpoint is used to authenticate and obtain an access token.

import requests

path = "<base_url>" # the base url path provided during registration
url = f"{path}/login"
data = {
  "username": "<your_email>", # the email you provided
  "password": "<your_password>" # the password you have received in the email
}
headers = {"Content-Type": "application/x-www-form-urlencoded"}

resp = requests.post(url, data=data, headers=headers)
print(resp.json())
# JSON response example:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "Access token",
#   "expires_in_minutes": "60"
# }
Token Expiration
  • Access tokens are time-limited. Once expires_in_minutes is reached, the token becomes invalid.
  • If you receive an authentication or authorization error due to an expired or invalid token, repeat the /login request with your email and password to obtain a new access token.

Diagnosis Support​

The diagnosis support endpoint provides a ranked list of probable conditions based on skin images.

Example Images

You can find example images for testing this endpoint in the Materials section. These images include various dermatological conditions and test scenarios that you can use to validate your integration.

import requests
import base64

base_url = "<base_url>"  # the base url path provided during registration
url = f"{base_url}/diagnosis-support"

image_path = "<path_to_image>"  # Replace with the path to your image file (e.g., "lesion_image.jpg")
with open(image_path, "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

json_payload = {
    "payload": [{
        "contentAttachment": {
            "data": image_data
        }
    }]
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <access_token>"  # obtained from /login endpoint
}

response = requests.post(url, json=json_payload, headers=headers)
result = response.json()

Severity Assessment​

The severity assessment endpoints assess the severity of a patient's condition using validated scoring systems. There are three types of severity assessment:

  • Manual: Uses questionnaire responses provided by the clinician or patient
  • Automatic Local: AI-based assessment from images for specific body areas
  • Automatic Global: AI-based assessment from images for the entire body

Manual Severity Assessment​

The manual severity assessment endpoint calculates severity scores based on questionnaire responses.

import requests

base_url = "<base_url>"  # the base url path provided during registration
url = f"{base_url}/severity-assessment/manual"

json_payload = {
    "bodySite": "armLeft", # for a complete list of available body site codes, refer to the Body Sites endpoint
    "knownCondition": {
        "conclusion": {
            "text": "psoriasis"  # plain text representation of the concept (local code that the concept was coded with).
        }
    },
    "scoringSystem": {
        "pure4": {  # for a complete list of available scoring systems, refer to the Questionnaires endpoint
            "questionnaireResponse": {
                "item": {
                    "question1": 1,
                    "question2": 0,
                    "question3": 0,
                    "question4": 1
                }
            }
        }
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <access_token>"  # obtained from /login endpoint
}

response = requests.post(url, json=json_payload, headers=headers)
result = response.json()

Automatic Local Severity Assessment​

The automatic local severity assessment endpoint uses AI to analyze images and calculate severity scores for specific body areas.

import requests
import base64

base_url = "<base_url>"  # the base url path provided during registration
url = f"{base_url}/severity-assessment/automatic/local"

image_path = "<path_to_image>"  # Replace with the path to your image file (e.g., "lesion_image.jpg")
with open(image_path, "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

json_payload = {
    "payload": {
        "contentAttachment": {
            "data": image_data
        }
    },
    "bodySite": "armLeft",  # for a complete list of available body site codes, refer to the Body Sites endpoint
    "knownCondition": {
        "conclusion": {
            "text": "psoriasis"  # plain text representation of the concept (local code that the concept was coded with).
        }
    },
    "scoringSystem": {
        "apasi": {  # for a complete list of available scoring systems, refer to the Questionnaires endpoint
            "questionnaireResponse": {
                "item": {
                    "surface": 2
                }
            }
        }
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <access_token>"  # obtained from /login endpoint
}

response = requests.post(url, json=json_payload, headers=headers)
result = response.json()

Automatic Global Severity Assessment​

The automatic global severity assessment endpoint uses AI to analyze images and calculate severity scores for the entire body.

import requests
import base64

base_url = "<base_url>"  # the base url path provided during registration
url = f"{base_url}/severity-assessment/automatic/global"

image_folder = "<path_to_your_image_folder>"  # path to the folder where your images are stored

# List of all body sites
body_sites = [
    "armLeftBottom", "armLeftTop", "armRightBottom", "armRightTop",
    "faceFront", "faceLeft", "faceRight",
    "footLeft", "footRight",
    "handLeft", "handRight",
    "legsBack", "legsFront",
    "trunkBack", "trunkFront", "trunkLeft", "trunkRight"
]

# Build the items dictionary using a loop
items = {}
for body_site in body_sites:
    image_path = f"{image_folder}/{body_site}.jpg"
    with open(image_path, "rb") as image_file:
        image_data = base64.b64encode(image_file.read()).decode('utf-8')

    items[body_site] = {
        "payload": {
            "contentAttachment": {
                "data": image_data
            }
        }
    }

json_payload = {
    "knownCondition": {
        "conclusion": {
            "text": "vitiligo"  # plain text representation of the concept (local code that the concept was coded with).
        }
    },
    "scoringSystem": {
        "avasi": {
            "item": items
        }
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <access_token>"  # obtained from /login endpoint
}

response = requests.post(url, json=json_payload, headers=headers)
result = response.json()

Troubleshooting​

Please ensure that all requests and responses are formatted correctly according to the JSON API specification. For any issues encountered during integration or while generating PDFs, refer to the troubleshooting section in the official documentation or contact our support team for assistance.

Next steps​

Once you have fully read this page, you can proceed to the Endpoints section for detailed information about each endpointincluding request bodies, response structures, parameters, and usage examples.