Allergen API returns results inconsistent with the Canvas UI allergen autocomplete

[jayant-walvekar-falconeer]

We are programmatically searching the FHIR /Allergen endpoint and observing results that don't match what the Canvas UI's allergen autocomplete offers for the same search term on the same instance. Two different FDB codes for the same search term, and entries the UI clearly knows about are not returned by the FHIR endpoint.

---

Case 1 — chocolate

Request:

GET https://fumage-altoscare-dev.canvasmedical.com/Allergen?_text=chocolate
Authorization: Bearer <token>
Content-Type: application/fhir+json

Response (one entry, total=1):

{
  "resource": {
    "resourceType": "Allergen",
    "id": "fdb-2-114545",
    "code": {
      "coding": [
        { "system": "http://www.fdbhealth.com/", "code": "2-114545", "display": "Ex-Lax (sennosides)" },
        { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "217013" }
      ]
    }
  }
}

By contrast, the Canvas UI's allergen autocomplete on the same instance shows multiple chocolate-related entries when typing chocolate — including chocolate (ingredient), chocolate flavor (bulk) (medication), Chocolate Flavored Laxative (medication), chocolate hazelnut flav (bulk) (medication), etc. None of these are returned by /Allergen?_text=chocolate.

When chocolate (ingredient) is picked from the UI and committed to a note, the persisted coding on the allergy intolerance is:

"coding": [
  { "code": 19561, "system": "http://www.fdbhealth.com/", "display": "chocolate" }
]

So the UI catalog has FDB code 19561 for "chocolate", but the FHIR endpoint exposes a different FDB code (2-114545, "Ex-Lax (sennosides)") and never surfaces 19561 under any phrasing we tried (chocolate, chocolate (ingredient), chocolate ingredient).

---

Case 2 — pluralization

GET /Allergen?_text=sulfonamide        → 1 result: FDB 1-491 "Sulfa (Sulfonamide Antibiotics)" (FDB + SNOMED)
GET /Allergen?_text=sulfonamides       → total=0
GET /Allergen?_text=sulfonamides (sulfa) → total=0

The singular form returns the canonical category entry; the plural and the parenthetical-qualified form return nothing. Same clinical concept, but _text= appears to be strict on word form.

---

Questions for Canvas

1. Is /Allergen?_text= documented as the complete allergen catalog for an instance, or is it a deliberately filtered subset? If filtered, what's the filter (e.g. excludes "ingredient"-category entries)?
2. What API does the Canvas UI's allergen autocomplete use? Is it exposed for integration?
3. For FDB allergen codes, are the unprefixed codes (e.g. 19561 written by the UI on note commit) and the prefixed codes (e.g. 2-114545 returned by FHIR) in the same code-space, or are they different identifier systems? How should an integrator map between them?
4. What is the canonical FDB code Canvas considers correct for an allergy to "chocolate" recorded on a patient?
5. Is _text= expected to handle inflection (singular/plural) and parenthetical qualifiers, or is it strict-match? Is there a recommended search parameter for fuzzy/lexical-variant lookup?

We can share additional examples on request.

[rmagier1]

Hi Jayant,

This is the allergen-specific follow-up I promised on the medication thread (#1728) — and is it's the same underlying story as medications, so the model you've already internalized there carries straight over.

The short version

FHIR GET /Allergen and the Canvas UI's allergen autocomplete are two different catalogs, queried through two different matchers — exactly like /Medication vs. the chart's medication picker:

• FHIR GET /Allergen is backed by FDB's interoperability table — the set of allergens that have an external coding (RxNorm or SNOMED) mapping. It matches your _text as a literal case-insensitive substring against both the FDB description and the external (RxNorm/SNOMED) description.
• The UI autocomplete is backed by FDB's full DAM allergen pick-list — the complete curated allergen catalog, including ingredient-type concepts that have no external coding. It matches with Postgres full-text search.

So /Allergen is a deliberately narrower set (only externally-coded allergens) and matches differently. That single fact explains both of your cases. Walking through your five questions:

1. Is /Allergen?_text= the complete catalog, or a filtered subset?

It's a filtered subset. /Allergen only returns allergens that have an external interoperability coding — specifically an RxNorm ingredient/brand/precise-ingredient/multi-ingredient link or a SNOMED CT link. FDB allergen concepts that exist only on the FDB side with no external mapping are excluded by design.

That's exactly why chocolate (ingredient) (FDB 19561) never shows up: it's an FDB ingredient concept with no RxNorm/SNOMED external coding, so it isn't in the interop table that /Allergen searches. The UI's pick-list includes it; the FHIR interop endpoint doesn't.

And it's why a chocolate search returns the odd-looking Ex-Lax (sennosides): the endpoint matches _text against the external (RxNorm) description as well as the FDB one. That allergen's RxNorm description evidently contains the word "chocolate" (it's a chocolate-flavored laxative product), so it matched on the external-description side even though its FDB display ("Ex-Lax (sennosides)") doesn't contain "chocolate." It's a real match, just not the one you wanted.

2. What API does the UI autocomplete use? Is it exposed?

The UI autocomplete is backed by the DAM allergen pick-list, which is exposed through the ontologies service and — most usefully for you — is wrapped by the same MSF coding_lookup plugin I pointed you at on the medication thread. That plugin has an /allergy_search endpoint alongside /medication_search:

GET /plugin-io/api/coding_lookup/allergy_search?text=chocolate
Authorization: <your-api-key>

It accepts text or rxnorm_code, and it queries the pick-list (the same catalog the UI uses), returning {count, results} with each result's concept_id, concept_type, and a ready-to-use code. For UI parity, this is the endpoint to use — not FHIR /Allergen. chocolate through /allergy_search will surface the ingredient entries (including 19561) that /Allergen omits.

3. Are the unprefixed UI codes and the prefixed FHIR codes the same code-space?

Yes — same dam_allergen_concept_id space, just two representations:

• The UI persists the bare concept id on the committed allergy coding — 19561 — with the allergen type stored separately as the allergy's category.
• FHIR /Allergen represents the same kind of identifier as {type}-{concept_id} — e.g. 2-114545 is type 2 (medication) + concept id 114545. The FHIR resource id is fdb-{type}-{concept_id} (the type segment is 1 = allergy group, 2 = medication, 6 = ingredient — the same {1,2,6} scheme the SDK and the chart use).

To map between them: split the FHIR code on - → the first part is the type ({1,2,6}), the second is the bare concept id. Combine them back as fdb-{type}-{id} for a FHIR id.

One important caveat so this doesn't bite you: 2-114545 and 19561 are not two encodings of the same concept. They're genuinely different allergens — your chocolate search matched Ex-Lax (concept 114545) on FHIR and chocolate (concept 19561) in the UI. So the discrepancy you saw isn't a code-format mismatch to reconcile; it's that the two endpoints searched different catalogs and returned different rows.

4. What's the canonical FDB code for an allergy to "chocolate"?

19561 — the FDB ingredient concept (type 6, "ingredient"), which is what the UI persists when a provider picks chocolate (ingredient) and commits. That's the value to use with AllergyCommand (concept_id 19561, concept_type 6 / AllergenType.INGREDIENT). It's absent from FHIR /Allergen purely because it has no external RxNorm/SNOMED link.

5. Does _text handle inflection (singular/plural) and parentheticals?

No — both catalogs are strict on word form; neither stems.

• On FHIR /Allergen, _text is a literal substring match, so sulfonamides (plural) doesn't match the description "Sulfa (Sulfonamide Antibiotics)" — the stored word is the singular "Sulfonamide", and the literal substring "sulfonamides" isn't present. sulfonamide (singular) matches; sulfonamides doesn't. The parenthetical form sulfonamides (sulfa) fails for the same reason (no literal substring match).
• The pick-list (/allergy_search) uses full-text search with prefix matching, which is more forgiving for truncation (e.g. sulfonamide will prefix-match), but it still doesn't do linguistic stemming — it won't fold sulfonamides → sulfonamide either, because the indexed token is the shorter "sulfonamide" and a longer prefix can't match it.

There's no fuzzy/lexical-variant search parameter today on either surface. Practical guidance: query the singular/root form and strip parenthetical qualifiers before searching. If you need plural-tolerant matching, normalize the query on your side (e.g. drop a trailing "s", strip (...)), or search on a distinctive root token.

Net recommendation (mirrors the medication thread)

For allergen lookups that should match what providers see in the chart, use the DAM pick-list via the MSF coding_lookup plugin's /allergy_search endpoint, not FHIR GET /Allergen. FHIR /Allergen is specifically the externally-coded (RxNorm/SNOMED) interop subset — it's the right tool when you're starting from an RxNorm/SNOMED code and want the FDB allergen, but it is not the chart's catalog and shouldn't be treated as the complete allergen list. The pick-list is what the UI uses, includes the ingredient concepts (chocolate 19561), and gives you concept ids that resolve cleanly through AllergyCommand.

I'm also flagging internally that /Allergen being a filtered interop subset (and /Medication being a broader-but-different catalog than the chart) isn't documented anywhere an integrator would find it — that's a real gap, and it ties into the per-resource source-of-truth documentation we discussed on #1728.