---
title: "Link entity"
method: POST
path: "/med-link/nel/link"
tags: ["Entity Linking"]
---

# Link entity

`POST /med-link/nel/link`

Links a single free-text medical entity to candidate codes from the requested ontology. The `metadata` field carries ontology-specific hints — it is **strongly recommended for LOINC** (a unit can change the linked code) and **optional for medication**. SNOMED CT and ICD-10-CM Comprehend do not use `metadata`.

## Request body

- NELRequest
  - `query` string, required — Free-text medical entity to link.
  - `ontology` string, required — Ontology name. One of: `snomed`, `loinc`, `medication`, `icd-10-cm`.
  - `version` string, required — Ontology version. Fetch valid values from `GET /med-link/registry/`.
  - `top_k` integer — Number of candidate results to return.
  - `metadata` object — Ontology-specific hints. Recommended for LOINC (`unit`, `value`, `specimen`, …) and optional for medication (`form`, `generic_name`, `dose_unit`, …). Ignored by SNOMED CT and ICD-10-CM Comprehend.
  - `request_id` string, nullable — Optional request ID. Generated automatically if omitted.

## Response `200`

Candidate codes for the query, ranked by relevance.

- NELResponse
  - `request_id` string, required
  - `query` string, required
  - `query_breakdown` object, nullable — How the query was parsed. Present for LOINC, medication and ICD-10-CM Comprehend; `null` for SNOMED CT.
  - `results` NELResult[], required
    - `term_id` string, required — The ontology code for this candidate.
    - `term_name` string, required — Human-readable name of the candidate term.
    - `score` number, nullable — Relevance/confidence of the candidate. `null` for medication, where matching is reported through `metadata.matching_breakdown` instead.
    - `is_linked` boolean — `true` when the pipeline is confident this candidate is the correct single match for the query.
    - `metadata` object, nullable — Ontology-specific detail about the candidate (e.g. `semantic_tag` for SNOMED, `matching_breakdown`/`eka_id` for LOINC, `generic_name`/`matching_breakdown` for medication).
  - `ontology` string, required
  - `version` string, required
  - `index_name` string, required — The index that served the request.
  - `model_version` string, nullable

## Other responses

- `422` — Validation error — a required field is missing or malformed.

---

[API](https://skmtc.net/eka/apis/eka-developer-apis.md) · [All operations](https://skmtc.net/eka/apis/eka-developer-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eka/eka-developer-apis/versions/9ea23456f722/schema)