canonical: https://jentic.com/apis/hlaverify.com/hlaverify

# HLA-Verify

The HLA-Verify API validates HLA nomenclature and checks donor-recipient match arithmetic against a pinned IPD-IMGT/HLA release. It classifies allele-shaped tokens in report text, normalizes reported typings to the current release, returns donor-recipient match verdicts under rules R1 through R6, assesses immunogenetic compatibility, and validates GL Strings. It is deterministic and stores nothing, and it neither needs nor accepts patient identifiers, so callers de-identify before sending.

## For AI agents

Validate HLA alleles and typings, normalize them to the current IPD-IMGT/HLA release, score donor-recipient matches, and check GL Strings, deterministically and without storing data.

## Scope

Does not store data, diagnose patients, or accept patient identifiers. Use for HLA nomenclature validation and donor-recipient match arithmetic only.

## Capabilities

- Classify every allele-shaped token in HLA report text or model output
- Normalize reported HLA typings to the current IPD-IMGT/HLA release
- Look up facts for one allele, prefix, group, or deleted name
- Return a donor-recipient match verdict using rules R1 through R6
- QC-check an HLA typing across all loci for resolution and renames
- Assess donor and recipient immunogenetic compatibility including the HLA-B leader
- Validate and normalize a GL String against its grammar

## Use cases

### HLA Typing QC

Quality-check an HLA typing before it enters a report so stale names and resolution errors are caught against the current release. The API checks a typing across all loci and flags renames, locus mismatches, and resolution issues deterministically. Histocompatibility labs use this as an automated QC step that does not depend on a model or stored data.

Example prompt: POST `/v1/typing/check` with the typing string and review the resolution and locus-mismatch findings it returns.

### Donor-Recipient Match Verification

Confirm a donor-recipient HLA match using explicit rules rather than hand arithmetic, so the verdict is reproducible. The API returns a match verdict under rules R1 through R6 and a separate immunogenetic compatibility assessment. Transplant workflows use this to double-check match calls before they are acted on.

Example prompt: POST `/v1/match` with the donor and recipient typings and return the R1 through R6 verdict.

### Report Text Nomenclature Validation

Scan free text or model output for HLA allele names and bring any reported typings up to the current release. The API classifies each allele-shaped token in the text and normalizes reported typings deterministically. Teams use this to validate HLA names in documents without sending any patient identifiers.

Example prompt: POST `/v1/verify` with the report text to classify allele tokens, then POST `/v1/normalize` to bring reported typings to the current release.

### Agent-Assisted Nomenclature Check

An AI agent validates the HLA names in generated or transcribed output before a human relies on them, flagging deleted or renamed alleles. Through Jentic the agent discovers the verify and normalize operations, loads their schemas, and runs them without storing any input. This lets a clinical-writing assistant self-check HLA nomenclature on the fly.

Example prompt: Search Jentic for 'validate HLA typing', call POST `/v1/verify` on the model output, and flag any token the response marks as deleted or renamed.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/verify` | Classify allele-shaped tokens in report text or model output |
| POST | `/v1/normalize` | Normalize reported typings to the current release |
| GET | `/v1/allele/{name}` | Facts for one allele, prefix, group, or deleted name |
| POST | `/v1/match` | Donor-recipient match verdict (rules R1 to R6) |
| POST | `/v1/typing/check` | QC-check one HLA typing across all loci |
| POST | `/v1/compat` | Donor and recipient immunogenetic compatibility |
| POST | `/v1/glstring` | Validate and normalize a GL String |

## Key resources

- **Verification** — Classify allele tokens in text and QC-check a full HLA typing
- **Normalization** — Normalize reported typings and GL Strings to the current release
- **Allele Facts** — Look up facts for an allele, prefix, group, or deleted name
- **Matching** — Return donor-recipient match verdicts and immunogenetic compatibility

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 44 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 20 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 77 / 100
- **View full report:** https://jentic.com/apis/hlaverify.com/hlaverify/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring HLA-Verify by hand means attaching the X-API-Key header and chaining the verify, normalize, and match calls while keeping patient identifiers out of every request. Through Jentic you install once, import HLA-Verify from the API Directory, store the key once, and your agent calls the validation operations.
- **Permission scoping:** HLA-Verify carries the typings, GL Strings, and report text inside the request body, so a rule bounds which operations your agent may call rather than which record. You can allow just the verify, normalize, and match operations and keep the checkout and billing endpoints out of the agent's reach.
- **Credential handling:** Your HLA-Verify API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'validate HLA typing' or 'check a donor match', and Jentic returns the matching HLA-Verify operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **NLM Clinical Table Search Service** — Reference lookups for medical codes and terminology
- **DrChrono API** — EHR that holds the clinical records typings come from
- **Epic on FHIR** — FHIR access to clinical data in Epic systems

## FAQ

### Is there an HLA-Verify MCP server?

Yes. HLA-Verify exposes a remote MCP endpoint over streamable HTTP. You can also connect HLA-Verify directly through Jentic: your agent gets the full 15-endpoint surface without loading another server's tool definitions into its context, your API key is injected at call time by your self-hosted instance, and your own rules decide which operations the agent may call.

### What authentication does HLA-Verify use?

HLA-Verify authenticates with an API key in the X-API-Key header, per its OpenAPI spec, and some endpoints are also reachable without a key during the public beta. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt or logs.

### Can I verify a donor-recipient match with HLA-Verify?

Yes. POST `/v1/match` returns a donor-recipient match verdict under rules R1 through R6, and POST `/v1/compat` assesses immunogenetic compatibility including the HLA-B leader. Both run deterministically and store nothing from the request.

### What are the rate limits for HLA-Verify?

The OpenAPI spec does not publish numeric rate limits; HLA-Verify lists its published prices and limits on its pricing endpoint. See the HLA-Verify pricing page at https://hlaverify.com/pricing for the current limits that apply to your tier.

### How do I validate an HLA typing through Jentic?

Search Jentic with the query 'validate HLA typing', load the schema for POST `/v1/typing/check`, and execute it with the typing string to get resolution and rename findings. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with HLA-Verify?

Yes. Write a rule that allows only the read and validation operations you need, such as POST `/v1/verify` and POST `/v1/typing/check`, so the agent can check nomenclature but cannot start a checkout or touch billing endpoints, and every call it makes is logged. Because the service stores nothing and refuses patient identifiers, the agent only ever handles the de-identified tokens you pass.