The medical comprehend endpoint analyzes unstructured medical text to extract entities and label them with standardized medical codes. Each extracted entity comes with a confidence score, making it useful for processing clinical notes, medical records, and other healthcare-related documents.

​
Use cases

  • Automating medical records processing and classification
  • Extracting diagnosis codes from clinical notes for billing and insurance purposes
  • Creating structured datasets from unstructured medical documentation
  • Identifying and categorizing medications and their attributes in patient records
  • Standardizing medical terminology across different healthcare systems using SNOMED CT codes

You need an API key to access the Writer API. Get an API key by following the steps in the API quickstart.

We recommend setting the API key as an environment variable in a .env file with the name WRITER_API_KEY.

​
Endpoint overview

URL: POST https://api.writer.com/v1/tools/comprehend/medical

curl --location 'https://api.writer.com/v1/tools/comprehend/medical' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $WRITER_API_KEY" \
--data '{
    "content": "the symptoms are soreness, a temperature and cough", 
    "response_type": "SNOMED CT"
}'

​
Request body

The request body includes the following parameters:

ParameterTypeDescription
contentstringRequired. The medical text to analyze.
response_typestringRequired. The desired response format.

Response type options include:

  • Entities: Returns medical entities with their categories.
  • RxNorm: RxNorm provides normalized names and unique identifiers for medicines and drugs, allowing computer systems to communicate drug-related information efficiently and unambiguously.
  • ICD-10-CM: ICD-10-CM is a standardized system used to code diseases and medical conditions (morbidity) data.
  • SNOMED CT: SNOMED CT is a standardized, multilingual vocabulary of clinical terminology that is used by physicians and other healthcare providers for the electronic exchange of health information.

​
Response parameters

Returns an array of medical entities, where each entity includes:

ParameterTypeDescription
categorystringThe medical category of the entity
textstringThe actual text that was identified
scorefloatConfidence score for the entity (0-1)
traitsarrayArray of trait objects with names and scores
conceptsarrayArray of medical concepts with codes and descriptions
attributesarrayRelated attributes with their own scores and relationships
typestringThe entity type

See the full response schema for more details.

example response
{
  "entities": [
    {
      "category": "MEDICAL_CONDITION",
      "begin_offset": 17,
      "end_offset": 25,
      "text": "soreness",
      "traits": [
        {
          "score": 0.5752319693565369,
          "name": "HYPOTHETICAL"
        },
        {
          "score": 0.7299559712409973,
          "name": "SYMPTOM"
        }
      ],
      "concepts": [
        {
          "code": "71393004",
          "score": 0.9435068368911743,
          "description": "Soreness (finding)"
        },
        {
          "code": "279074008",
          "score": 0.27141574025154114,
          "description": "Sore skin (finding)"
        },
        {
          "code": "247348008",
          "score": 0.20372514426708221,
          "description": "Tenderness (finding)"
        },
        {
          "code": "410713007",
          "score": 0.18387910723686218,
          "description": "Sore sensation quality (qualifier value)"
        },
        {
          "code": "267102003",
          "score": 0.15431177616119385,
          "description": "Sore throat symptom (finding)"
        }
      ],
      "score": 0.7172441482543945,
      "attributes": [],
      "type": "DX_NAME"
    },
    {
      "category": "MEDICAL_CONDITION",
      "begin_offset": 29,
      "end_offset": 40,
      "text": "temperature",
      "traits": [
        {
          "score": 0.7299559712409973,
          "name": "HYPOTHETICAL"
        },
        {
          "score": 0.8787732124328613,
          "name": "SYMPTOM"
        }
      ],
      "concepts": [
        {
          "code": "703421000",
          "score": 0.4236489236354828,
          "description": "Temperature (observable entity)"
        },
        {
          "code": "386661006",
          "score": 0.4029766321182251,
          "description": "Fever (finding)"
        },
        {
          "code": "246508008",
          "score": 0.26857706904411316,
          "description": "Temperature (attribute)"
        },
        {
          "code": "56342008",
          "score": 0.26122674345970154,
          "description": "Temperature taking (procedure)"
        },
        {
          "code": "722490005",
          "score": 0.1763012409210205,
          "description": "Temperature (property) (qualifier value)"
        }
      ],
      "score": 0.8435389995574951,
      "attributes": [],
      "type": "DX_NAME"
    },
    {
      "category": "MEDICAL_CONDITION",
      "begin_offset": 45,
      "end_offset": 50,
      "text": "cough",
      "traits": [
        {
          "score": 0.9013108015060425,
          "name": "HYPOTHETICAL"
        },
        {
          "score": 0.9817302823066711,
          "name": "SYMPTOM"
        }
      ],
      "concepts": [
        {
          "code": "49727002",
          "score": 0.9173739552497864,
          "description": "Cough (finding)"
        },
        {
          "code": "263731006",
          "score": 0.20544156432151794,
          "description": "Coughing (observable entity)"
        },
        {
          "code": "247410004",
          "score": 0.18926720321178436,
          "description": "Painful cough (finding)"
        },
        {
          "code": "11833005",
          "score": 0.18911097943782806,
          "description": "Dry cough (finding)"
        },
        {
          "code": "135883003",
          "score": 0.1864289492368698,
          "description": "Cough with fever (finding)"
        }
      ],
      "score": 0.9584784507751465,
      "attributes": [],
      "type": "DX_NAME"
    }
  ]
}