Guides › APIs and bioinformatics tools

An HLA allele lookup API: verify, normalize, allele and history calls

Updated 2026-10-30 · allele examples checked against IPD-IMGT/HLA 3.66.0 on 2026-10-30

The HLA-Verify API answers questions about HLA allele names against one pinned IPD-IMGT/HLA release, currently 3.66.0. Four calls cover most needs: POST /v1/verify checks every allele-shaped token in free text, POST /v1/normalize resolves a batch of reported names to current ones, GET /v1/allele/{name} returns the facts about one name, and the history calls (GET /v1/allele/{name}/history, POST /v1/translate, GET /v1/releases/diff) answer what a name meant in another release.

Every response carries the release it was computed from. This guide shows which call to use for which question, with responses taken from the engine at release 3.66.0. The API reference has the full schemas.

Which call answers which question

The first three are the everyday calls. The history calls matter for archives and for keeping stored data current.

Verify: check free text

POST /v1/verify takes {"text": "..."} and returns a verdict for every allele-shaped token it finds: valid, deleted, group, fabricated_group, hallucinated, mac_code or out_of_scope, plus counts and a single clean flag. It is built for typing reports, comment fields and AI-written text, where names arrive inside prose.

Sent the text A*24:09N B*5701 DQB1*05:03:26:99 A*02:01:14Q C*04:09N, the engine at 3.66.0 returned:

• A*24:09N: valid, flag null_allele;
• B*5701: valid, current two-field name B*57:01, flag deprecated_name;
• DQB1*05:03:26:99: hallucinated, no such name in any release;
• A*02:01:14Q: deleted, successor A*02:01:14;
• C*04:09N: deleted, successor C*04:09L;
• clean: false.

A fabricated name is a result, not an error, so verify never fails on bad names. The verdicts guide explains each status and what to do with it.

Normalize: a column in, a clean column out

POST /v1/normalize takes {"typings": [...]} and returns one row per input with current_name, allele_2field, g_group and flags. It accepts every era and shorthand: colon-less names, Cw, deleted names, G and P group names, XX codes, the two-field g notation and an optional HLA- prefix. Each shorthand leaves a flag, so nothing is converted silently. Input that cannot be resolved returns UNRESOLVABLE, never a guess.

Examples at 3.66.0: A*0101 becomes A*01:01 with deprecated_name; Cw*07:02 becomes C*07:02; A*02:01:01G reduces to the two-field A*02:01 with g_group_name; A*02:AB is UNRESOLVABLE with mac_code, because multiple allele codes are recognised but not expanded.

One caveat: normalize converts colon-less names mechanically, so pre-2010 rollover names such as A*9201 come back unresolvable. Use translate or history for those.

Allele: the facts for one name

GET /v1/allele/{name} returns what the release says about a name. What comes back depends on what the name is:

A name that was never assigned returns HTTP 404 with a message naming both forms, for example that B*9999 stands for B*99:99, which is not assigned in release 3.66.0. Allele names contain * and :, which some HTTP clients need encoded in the path.

History, translate and diff

These calls answer from the IPD-IMGT/HLA name history, every release from 1.05.0 to the pin, keyed on the permanent HLA ID.

• GET /v1/allele/{name}/history returns the HLA ID, the current name, every name it has had release by release and why a name was retired. For A*02:01:14 the history is A*020114 (2.18.0 to 2.28.0), A*02:01:14 (3.00.0 to 3.03.0), A*02:01:14Q (3.04.0 to 3.65.0) and A*02:01:14 again in 3.66.0.
• POST /v1/translate maps a list of names from one release to another and labels each row, for example unchanged, renamed, deleted with reason and successor, or unknown. It follows A*9201 through the history to A*02:101:01.
• GET /v1/releases/diff?from=3.65.0&to=3.66.0 lists every name added, removed and renamed: 772, 0 and 24 for that pair.

The release comparison guide shows how to compute the same diff from the release files.

Batching, limits and errors

Anonymous use allows 100 calls a day per IP address and 60 a minute, with quotas reset at midnight UTC. That makes batching the main design decision: one normalize or verify call can carry a whole column, up to 250 names per normalize call without a key and 5,000 with a Lab-tier key, which is free during early access.

Send allele names and typing strings only, never patient identifiers. If you cannot send anything outside your network, the service also ships as a container that pins a release with the HLA_VERIFY_TAG setting and fetches the reference files from the official source at startup.

Frequently asked questions

Which API call checks HLA allele names in a typing report?

POST /v1/verify. It accepts free text and returns a verdict for every allele-shaped token, plus a clean flag that is true only when there are no hallucinated, fabricated-group or deleted names.

How do I convert old HLA names to current ones through an API?

Send them in one batch to POST /v1/normalize, which returns the current name and a deprecated_name flag for each. For pre-2010 rollover names, use POST /v1/translate, which follows the name history.

What does the API return for an HLA name that does not exist?

/v1/verify reports it as hallucinated. GET /v1/allele/{name} returns HTTP 404 with a message saying the name is not assigned in the pinned release.

Which IPD-IMGT/HLA release does the API use?

One release is compiled into the service and named in every response; it is 3.66.0 at the time of writing. GET /healthz reports the pin.