obscyro

Api / Normalize

/v1/normalize

Map free-text clinical phrases to ranked SNOMED concept candidates using exact, full-text, and trigram matching.

POST/v1/normalize

Normalize is the workhorse endpoint. Given a clinical phrase, it returns up to limit SNOMED concept candidates ranked by match quality. The matcher runs three strategies in a single batched query and deduplicates by concept:

  1. Exact — case-insensitive equality against active descriptions.
  2. FTS — PostgreSQL to_tsvector / ts_rank full-text search.
  3. Trigram — pg_trgm similarity for typos and abbreviations.

Request body

Parameters

  • textstringrequired
    The clinical phrase to match. After trimming, must be at least 2 characters; otherwise the request returns 400 INVALID_INPUT.
  • limitintegeroptionaldefault: 5
    How many candidates to return, between 1 and 50.

Response

Candidates ranked best-first
{
  "matches": [
    {
      "code": "22298006",
      "term": "Myocardial infarction",
      "conceptName": "Myocardial infarction",
      "confidence": 0.94,
      "matchType": "fts"
    },
    {
      "code": "57054005",
      "term": "Acute myocardial infarction",
      "conceptName": "Acute myocardial infarction",
      "confidence": 0.88,
      "matchType": "fts"
    }
  ]
}

Match shape

  • codestringoptional
    SCTID of the matched concept.
  • termstringoptional
    The actual SNOMED description that matched (synonym or FSN).
  • conceptNamestringoptional
    The preferred display term for the concept (shortest active synonym, falling back to FSN).
  • confidencenumberoptional
    A score in [0, 1]. For exact it is 1.0; for fts it is the normalized ts_rank; for trigram it is the similarity() score.
  • matchType"exact" | "fts" | "trigram"optional
    Which strategy produced this candidate. Use this to decide your minimum acceptable confidence per use case.

Examples

curl -X POST https://api.obscyro.com/v1/normalize \
  -H "Authorization: Bearer $OBS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "type 2 diabetes",
    "limit": 5
  }'

Tips

  • For ingestion pipelines that handle thousands of phrases, use /v1/normalize-batch — it counts as a single rate-limit hit.
  • If you need the right concept among multiple plausible matches, pass the candidates through /v1/disambiguate with surrounding clinical context.
  • Trigram matches with confidence below ~0.55 are usually noise. Pick a threshold that suits your false-positive tolerance.

Errors

  • VALIDATION_ERROR

    Body did not pass schema validation (missing text, bad limit).

  • INVALID_INPUT

    text was shorter than 2 characters after trimming.

  • INVALID_API_KEY

    Missing or invalid bearer token.

  • RATE_LIMITED

    Per-minute rate limit exceeded for this key.