cpt lookuphealthcare apimedical codingomop cdmhealth tech

CPT4 Lookup with OMOPHub: UMLS Validation and API Guide

James Park, MSJames Park, MS
February 22, 20268 min read
CPT4 Lookup with OMOPHub: UMLS Validation and API Guide

CPT4 Lookup with OMOPHub: UMLS Validation and API Guide

Programmatic CPT lookup can remove brittle spreadsheets and manual crosswalks from healthcare applications, but CPT is not an unrestricted public vocabulary. A correct integration needs both reliable terminology APIs and an explicit licensing boundary.

OMOPHub provides CPT4 content only to authenticated users who complete annual UMLS validation in the OMOPHub Dashboard. This guide explains that access model and shows how to look up, search, map, and navigate CPT4 concepts after validation.

Important: CPT® is a registered trademark of the American Medical Association. CPT content is copyright American Medical Association. All rights reserved. UMLS validation confirms access to the NLM service; it does not transfer AMA rights or replace your organization's responsibility to obtain and follow any required CPT license.

Why Move CPT Lookups Out of Spreadsheets?

Static files and spreadsheets are difficult to keep synchronized with terminology releases. They also make it easy for deprecated codes, transcription errors, and undocumented local changes to enter ETL pipelines.

A hand interacts with a tablet displaying API code, digitizing CPT codes from a paper document, with colorful watercolor splashes.

An API-based workflow gives you:

  • Versioned vocabulary data. Responses identify the OMOP vocabulary release used for the request.
  • Consistent validity metadata. Concepts include validity dates and invalidation status.
  • Search and mapping APIs. The same access model applies to direct lookup, text and semantic search, mappings, hierarchy, relationships, statistics, and FHIR operations.
  • A fail-closed licensing boundary. CPT4 content is returned only when the authenticated API-key owner has a current validation grant.

OMOPHub follows OHDSI ATHENA vocabulary releases. It does not claim that every request reflects an AMA update in real time. Pin a vocabulary release when reproducibility matters and review the release metadata when upgrading.

Before Your First CPT4 Request

CPT4 access requires two separate credentials:

  1. An active UMLS account and UMLS API key from your UTS profile.
  2. An OMOPHub API key from the OMOPHub Dashboard.

In the Dashboard, open Settings → Vocabulary access, enter your UMLS API key, and select Validate. OMOPHub sends the key to NLM for validation and does not store it. Only the authorization result, validation time, and expiration date are retained.

A successful validation:

  • enables CPT4 for every active OMOPHub API key owned by the same user;
  • never grants access to another OMOPHub user;
  • expires at 00:00 UTC on January 1 of the next calendar year; and
  • must be repeated after expiration.

If validation is absent or expired, an explicit CPT4 request returns HTTP 403 with the stable error code vocabulary_restricted. GPI and MedDRA remain unavailable regardless of CPT4 validation. The public OMOPHub Tools application also remains public-only and does not expose CPT4.

For the full policy, see the CPT4 access documentation.

Look Up a CPT4 Concept by Code

After Dashboard validation, use the vocabulary-specific lookup endpoint. Replace YOUR_CPT_CODE with a code that your organization is permitted to use and YOUR_API_KEY with an OMOPHub API key belonging to the validated user.

curl "https://api.omophub.com/v1/concepts/by-code/CPT4/YOUR_CPT_CODE" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response uses the standard OMOPHub envelope:

{
  "success": true,
  "data": {
    "concept_id": 123456,
    "concept_name": "...",
    "concept_code": "YOUR_CPT_CODE",
    "vocabulary_id": "CPT4",
    "domain_id": "Procedure",
    "concept_class_id": "...",
    "standard_concept": "S",
    "valid_start_date": "...",
    "valid_end_date": "...",
    "invalid_reason": null,
    "is_valid": true
  },
  "meta": {
    "request_id": "...",
    "timestamp": "...",
    "vocab_release": "..."
  }
}

Check vocab_release, valid_start_date, valid_end_date, and invalid_reason before using a result in a longitudinal workflow. Do not hard-code OMOP concept_id values across releases without validating them against the release your pipeline uses.

Search CPT4 by Clinical Text

When you have a description rather than a code, filter search explicitly to CPT4:

curl --get "https://api.omophub.com/v1/search/concepts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=YOUR CLINICAL DESCRIPTION" \
  --data-urlencode "vocabulary_ids=CPT4" \
  --data-urlencode "domain_ids=Procedure" \
  --data-urlencode "page_size=20"

Explicit vocabulary and domain filters reduce noise and make the request's intent clear. Search results are candidate terminology matches, not coding advice; your clinical or coding workflow remains responsible for choosing the appropriate code.

Use the Python SDK

Install the SDK and create a client:

pip install omophub

import omophub

client = omophub.OMOPHub(api_key="YOUR_API_KEY")

# Direct lookup by vocabulary and source code
concept = client.concepts.get_by_code("CPT4", "YOUR_CPT_CODE")
print(concept["concept_id"])
print(concept["vocabulary_id"])

# Text search restricted to CPT4 procedures
results = client.search.basic(
    "YOUR CLINICAL DESCRIPTION",
    vocabulary_ids=["CPT4"],
    domain_ids=["Procedure"],
    page_size=20,
)

for item in results["concepts"]:
    print(item["concept_code"], item["concept_name"])

The annual grant is associated with the OMOPHub user, not with a particular SDK instance. Any active API key owned by that validated user receives the same CPT4 access.

Use the R SDK

library(omophub)

client <- OMOPHubClient$new(api_key = "YOUR_API_KEY")

# Direct lookup
concept <- client$concepts$get_by_code("CPT4", "YOUR_CPT_CODE")
print(concept$concept_id)
print(concept$vocabulary_id)

# Filtered text search
results <- client$search$basic(
  "YOUR CLINICAL DESCRIPTION",
  vocabulary_ids = "CPT4",
  domain_ids = "Procedure",
  page_size = 20
)

for (item in results$data) {
  cat(sprintf("%s: %s\n", item$concept_code, item$concept_name))
}

OMOPHub uses page-based pagination: page starts at 1 and page_size controls the number of returned items. Do not use the older limit and offset parameters shown in previous versions of this article.

Once you have the OMOP concept_id returned by a validated lookup, you can inspect its relationships:

relationships = client.relationships.get(
    concept["concept_id"],
    relationship_ids=["Maps to", "Is a", "Subsumes"],
    page=1,
    page_size=50,
)

for relationship in relationships["data"]["relationships"]:
    print(relationship["relationship_id"])

To retrieve mappings to a target vocabulary:

mappings = client.mappings.get(
    concept["concept_id"],
    target_vocabulary="SNOMED",
    include_invalid=False,
)

for mapping in mappings["mappings"]:
    print(mapping["target_concept_id"], mapping["relationship_id"])

Access checks apply before OMOPHub returns CPT4 concepts, names, relationships, or mapping paths. An unvalidated user cannot use a mapping or hierarchy endpoint to bypass the restriction.

Mappings in an OMOP vocabulary release do not represent a measured probability or clinical confidence score. Review the relationship type, validity metadata, and target standard status before adopting a mapping in production.

Build a Compliant and Performant Integration

Digital security concept with cloud, padlock, and cache checklist on a white table.

Treat CPT as licensed content

OMOPHub's validation flow confirms that the user has active UMLS access. It does not make CPT public-domain content, transfer AMA rights, or eliminate the customer's licensing responsibilities. Review the AMA CPT licensing FAQ and the NLM UMLS license information with your legal or compliance team.

Cache deliberately

Caching can reduce repeated API calls, but a cache creates another stored copy of licensed content. Confirm that your organization's applicable terms allow the intended storage, users, geography, and retention period. Keep cache entries scoped to authorized users, attach the vocabulary release to cache keys, set an appropriate expiration, and remove access when the underlying authorization expires.

Keep credentials separate

Your UMLS key belongs only in the Dashboard validation form. Applications call OMOPHub with an OMOPHub API key. Do not place either credential in browser code, source control, logs, analytics events, or support tickets.

Use batch operations where appropriate

For larger jobs, deduplicate input codes and use OMOPHub batch endpoints rather than issuing one request for every source row. Respect your plan's rate and monthly limits, and keep authorization-aware caches isolated between users.

Frequently Asked Questions

Does an OMOPHub API key automatically include CPT4?

No. The owning Dashboard user must first complete annual UMLS validation. Without a current grant, explicit CPT4 requests return 403 vocabulary_restricted.

Does OMOPHub store my UMLS API key?

No. OMOPHub sends the submitted key to NLM for validation and stores only the validation decision and its validity window.

When must I revalidate?

Every successful grant expires at the beginning of the next calendar year, at 00:00 UTC on January 1. Revalidate in the Dashboard after that boundary.

Does validation cover my whole team?

It covers all active OMOPHub API keys owned by the same Dashboard user. It does not cross user accounts. Each separately authenticated user must validate their own access.

Can I use the public Concept Lookup tool for CPT4?

No. OMOPHub Tools is intentionally public-only. Use an authenticated OMOPHub API or FHIR request after validating in the Dashboard.

How are CPT updates versioned?

OMOPHub publishes versioned OHDSI ATHENA releases. API responses identify the release used, and clients can pin a supported release with OMOPHub's vocabulary-version controls. Review validity fields and release notes rather than assuming a code is current solely because a lookup succeeds.

Next Steps

  1. Confirm your organization's CPT licensing requirements.
  2. Obtain or renew your UMLS access and accept the current UMLS terms.
  3. Validate your UMLS API key under Dashboard → Settings → Vocabulary access.
  4. Create an OMOPHub API key and test a vocabulary-specific CPT4 lookup.
  5. Pin and record the vocabulary release used by production pipelines.

See the CPT4 access guide, API error reference, and Python or R SDK documentation for implementation details.

CPT® is a registered trademark of the American Medical Association. CPT content is copyright American Medical Association. All rights reserved.

Share:
Concept LookupGet API key