Compendium Search

Search the lab test compendium to find canonical tests and crosswalk them to available lab-specific test candidates.

This feature is in closed beta.

Interested in this feature? Get in touch with your Customer Success Manager.

POST /v3/compendium/search searches the compendium in two modes:

• canonical: find and rank canonical tests only.
• crosswalk: select one canonical test, then map it into per-lab candidates.

Request body

{
  "mode": "canonical | crosswalk",
  "query": "string (optional in crosswalk, required in canonical)",
  "loinc_set_hash": "string (crosswalk only)",
  "labs": ["labcorp", "quest", "bioreference", "sonora_quest"],
  "include_related": true,
  "limit": 3
}

Validation rules

Canonical mode

• query is required and must be non-empty.
• loinc_set_hash is not allowed.
• limit must be 1..10.

Crosswalk mode

• Exactly one of query or loinc_set_hash is required.
• limit must be 1..20.
• include_related controls whether related canonical candidates are returned.

If validation fails, the API returns HTTP 422.

Search modes

1) canonical

Purpose: return ranked canonical tests only.

Behavior:

• Returns:
  • selected_canonical: top candidate (or null).
  • canonical_candidates: ranked list (up to limit).
• per_lab and related are empty in this mode.

2) crosswalk

Purpose: choose one canonical test and expand it across labs.

Entry points:

• By text query: pick best canonical from query.
• By loinc_set_hash: load canonical directly by hash.

Behavior:

• If no canonical is found, response has:
  • selected_canonical = null
  • canonical_candidates = []
  • no per-lab candidates.
• If canonical is found, returns:
  • one selected_canonical and same item in canonical_candidates
  • per_lab: candidates grouped by lab slug
  • related: related canonical tests (if include_related=true)

Canonical tests

“Canonical tests” are normalized, cross-lab test concepts.

They are used to:

• normalize query intent (display_name, aliases, loinc_codes, etc.)
• create one canonical anchor (selected_canonical)
• crosswalk into concrete provider/lab tests (per_lab)

Canonical ranking combines match quality and popularity score. The selected labs filter which per-lab candidates are returned in crosswalk mode.

Output schema

{
  "mode": "canonical | crosswalk",
  "selected_canonical": {
    "loinc_set_hash": "string",
    "display_name": "string",
    "aliases": ["string"],
    "loinc_codes": ["string"],
    "provider_ids": ["string"],
    "loinc_components": ["string"],
    "loinc_groups": ["string"],
    "popularity_score": 0.0,
    "confidence": 0.0
  },
  "canonical_candidates": [
    {
      "loinc_set_hash": "string",
      "display_name": "string",
      "aliases": ["string"],
      "loinc_codes": ["string"],
      "provider_ids": ["string"],
      "loinc_components": ["string"],
      "loinc_groups": ["string"],
      "popularity_score": 0.0,
      "confidence": 0.0
    }
  ],
  "per_lab": {
    "quest": [
      {
        "marker_id": 0,
        "lab_id": 7,
        "lab_slug": "quest",
        "name": "string",
        "result_names": ["string"],
        "provider_id": "string",
        "loinc_set_hash": "string",
        "loinc_codes": ["string"],
        "loinc_components": ["string"],
        "loinc_groups": ["string"],
        "relation": "exact | subset | superset | overlap | suggested",
        "confidence": 0.0,
        "reason_codes": ["EXACT_LOINC_SET | SUBSET | SUPERSET | OVERLAP | NAME_MATCH | SYNONYM_MATCH"],
        "marker_popularity_score": 0.0
      }
    ]
  },
  "related": [
    {
      "canonical": {
        "loinc_set_hash": "string",
        "display_name": "string",
        "aliases": ["string"],
        "loinc_codes": ["string"],
        "provider_ids": ["string"],
        "loinc_components": ["string"],
        "loinc_groups": ["string"],
        "popularity_score": 0.0,
        "confidence": 0.0
      },
      "relation": "exact | subset | superset | overlap | suggested",
      "confidence": 0.0,
      "reason_codes": ["EXACT_LOINC_SET | SUBSET | SUPERSET | OVERLAP | NAME_MATCH | SYNONYM_MATCH"]
    }
  ]
}

Notes:

• confidence is model/service-generated and relative to result quality.
• Omitting labs defaults to all supported labs (labcorp, quest, bioreference, sonora_quest).

Example requests

Canonical mode

curl -X POST "$BASE_URL/v3/compendium/search" \
  -H "Content-Type: application/json" \
  -H "x-vital-api-key: $API_KEY" \
  -d '{
    "mode": "canonical",
    "query": "hemoglobin a1c",
    "labs": ["quest", "labcorp"],
    "limit": 5
  }'

Crosswalk mode by query

curl -X POST "$BASE_URL/v3/compendium/search" \
  -H "Content-Type: application/json" \
  -H "x-vital-api-key: $API_KEY" \
  -d '{
    "mode": "crosswalk",
    "query": "comprehensive metabolic panel",
    "labs": ["quest", "bioreference"],
    "include_related": true,
    "limit": 3
  }'

Crosswalk mode by canonical hash

curl -X POST "$BASE_URL/v3/compendium/search" \
  -H "Content-Type: application/json" \
  -H "x-vital-api-key: $API_KEY" \
  -d '{
    "mode": "crosswalk",
    "loinc_set_hash": "f0a1b2c3d4",
    "labs": ["labcorp", "quest"],
    "include_related": false,
    "limit": 3
  }'

For endpoint schema and try-it behavior, see the API reference page: Compendium Search.