CPT Get

Status: stable Category: lookup Added: 2026-10-14 Last reviewed: 2026-10-14

Summary

Returns one CPT code's record from the engine's curated codebook: its long and short descriptors, its CPT category, whether it is an add_on code, and its place in the book (section, subsection, heading). A structural key handed out by /api/lookup/cpt/tree is accepted too, so a detail view can resolve every node a tree shows.

The codebook covers occupational health delivered virtually — visits and work evaluations, physical and occupational therapy, behavioral health, remote monitoring and care management. It is not the full CPT code set: a well-formed CPT code outside it is a 404.

Endpoint

Field	Value
Method	`GET`
Path	`/api/lookup/cpt/get`
Full URL	`https://engine.tripod-health.com/api/lookup/cpt/get`
Authentication	API key (required)
Request body	none
Response body	`application/json`
Idempotent	Yes
Rate-limited	Yes

Authentication

Send a valid API key in the apikey header. See authentication.md.

Request

Headers

Header	Required	Description
`apikey`	Yes	Consumer API key.

Path parameters

None.

Query parameters

Parameter	Type	Required	Default	Description
`code`	`string`	Yes	—	A five-character CPT code: four digits, then a digit or a category letter (`99213`, `0001U`). A structural key from tree, such as `evaluation-management.office.est`, is also accepted.

Rejected with 400 naming code, never silently repaired:

A modifier suffix (99213-25, 99213 25). Modifiers are not part of a CPT code; send the five-character code.
A HCPCS Level II code (G2212, J1100). That is a different code set, which this resource does not hold.
Anything that is neither a five-character code nor a structural key.

Body

None.

Response

Success — `200 OK`

Request: GET /api/lookup/cpt/get?code=99213

{
  "code": "99213",
  "label": "Office or other outpatient visit for the evaluation and management of an established patient, which requires a medically appropriate history and/or examination and low level of medical decision making. When using total time on the date of the encounter for code selection, 20 minutes must be met or exceeded",
  "short_label": "Office o/p est low 20 min",
  "kind": "code",
  "billable": true,
  "ancestors": [
    {
      "code": "evaluation-management",
      "label": "Evaluation and Management",
      "kind": "section",
      "notes": {}
    },
    {
      "code": "evaluation-management.office",
      "label": "Office or Other Outpatient Services",
      "kind": "subsection",
      "notes": {}
    },
    {
      "code": "evaluation-management.office.est",
      "label": "Established Patient",
      "kind": "heading",
      "notes": {}
    }
  ],
  "notes": {},
  "add_on": false,
  "category": "I",
  "release": "2026",
  "request_id": "4c08be14-4a5a-4f98-9d7c-5fcd60a189ad",
  "timestamp": "2026-10-14T00:15:58.776Z"
}

Response fields

Field	Type	Always present	Description
`code`	`string`	Yes	The five-character code, or the structural key that was requested.
`label`	`string`	Yes	The long descriptor for a code; the heading text for a structural node.
`short_label`	`string \| null`	Yes	The short descriptor. `null` on structural nodes.
`kind`	`string`	Yes	`section`, `subsection`, `heading`, `subheading`, or `code`.
`billable`	`boolean`	Yes	`true` for a code, `false` for a structural node.
`ancestors`	`array`	Yes	The node's place in the book, section first, each `{ code, label, kind, notes }`. Empty for a section.
`notes`	`object`	Yes	Reserved for coding notes, in the same shape as the ICD-10-CM lookup. Currently `{}` for every CPT node.
`add_on`	`boolean`	No	Present on codes. `true` for an add-on code, which is reported only together with a primary procedure (for example `99417`, prolonged services).
`category`	`string`	No	Present on codes. The CPT category, from the code's shape: `I`, `II` (ends in `F`), `III` (ends in `T`), `PLA` (ends in `U`) or `MAAA` (ends in `M`).
`release`	`string`	Yes	The CPT year the codebook reflects, e.g. `2026`.
`request_id`	`string`	Yes	Correlation ID. Quote in support tickets.
`timestamp`	`string` (ISO 8601 UTC)	Yes	Server time when the response was emitted.

Status codes

Code	Meaning	When
`200`	OK	Code or structural node found.
`400`	`ValidationError`	`code` missing, carrying a modifier, a HCPCS Level II code, malformed, or repeated. `field` is `code`.
`401`	`Unauthenticated`	Missing or invalid API key.
`404`	`NotFound`	The value is well-formed but the codebook holds no such code or node.
`429`	`RateLimited`	Per-consumer rate limit exceeded.
`500`	`InternalError`	Unexpected failure. Quote `request_id` in the ticket.

Examples

curl

curl -sS "https://engine.tripod-health.com/api/lookup/cpt/get?code=99213" \
  -H "apikey: $ENGINE_API_KEY"

A structural key from tree

curl -sS "https://engine.tripod-health.com/api/lookup/cpt/get?code=evaluation-management.office.est" \
  -H "apikey: $ENGINE_API_KEY"

{
  "code": "evaluation-management.office.est",
  "label": "Established Patient",
  "short_label": null,
  "kind": "heading",
  "billable": false,
  "ancestors": [
    {
      "code": "evaluation-management",
      "label": "Evaluation and Management",
      "kind": "section",
      "notes": {}
    },
    {
      "code": "evaluation-management.office",
      "label": "Office or Other Outpatient Services",
      "kind": "subsection",
      "notes": {}
    }
  ],
  "notes": {},
  "release": "2026",
  "request_id": "93fa5fbb-bfc5-474a-b29f-92970dfadb31",
  "timestamp": "2026-10-14T00:21:31.381Z"
}

Python (`requests`)

# Uses the call() helper from quickstart.md.
record = call("GET", "/api/lookup/cpt/get?code=99213")
path = " > ".join(a["label"] for a in record["ancestors"])
print(f"{record['code']} ({record['short_label']}) in {path}")
print("add-on" if record["add_on"] else "primary", "category", record["category"])

Node.js (native `fetch`)

// Uses the call() helper from quickstart.md.
const record = await call("GET", "/api/lookup/cpt/get?code=99213");
const breadcrumb = record.ancestors.map((a) => a.label).join(" > ");
console.log(`${record.code}: ${record.short_label} (${breadcrumb})`);

TypeScript

type CptKind = "section" | "subsection" | "heading" | "subheading" | "code";

interface CptAncestor {
  code: string;
  label: string;
  kind: Exclude<CptKind, "code">;
  notes: Record<string, string[]>;
}

interface CptRecord {
  code: string;
  label: string;
  short_label: string | null;
  kind: CptKind;
  billable: boolean;
  ancestors: CptAncestor[];
  notes: Record<string, string[]>;
  add_on?: boolean;
  category?: "I" | "II" | "III" | "PLA" | "MAAA";
  release: string;
  request_id: string;
  timestamp: string;
}

const record = await call<CptRecord>("GET", "/api/lookup/cpt/get?code=99213");

Error scenarios

Modifier suffix

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/cpt/get?code=99213-25" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400):

{
  "timestamp": "2026-10-14T00:16:05.514Z",
  "error": "ValidationError",
  "message": "'code' carries a modifier; modifiers are not part of a CPT code -- send the five-character code, e.g. 99213",
  "field": "code",
  "request_id": "2a2dc4cc-9d7c-401d-9914-3d71daf91487"
}

HCPCS Level II code

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/cpt/get?code=G2212" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400):

{
  "timestamp": "2026-10-14T00:16:05.791Z",
  "error": "ValidationError",
  "message": "'code' looks like a HCPCS Level II code (G2212), which this resource does not cover; it holds CPT (HCPCS Level I) codes only",
  "field": "code",
  "request_id": "af8a7ab3-8bc2-47ef-84c7-18cf528aa1d0"
}

Valid CPT code outside the codebook

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/cpt/get?code=27447" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (404):

{
  "timestamp": "2026-10-14T00:16:06.143Z",
  "error": "NotFound",
  "message": "No CPT code or node '27447'",
  "request_id": "c15d7f03-f5c5-4761-8806-927a25b59c6c"
}

Intended use

Procedure detail panels that show a code's descriptor, its category, and where it sits in the book.
Flagging add-on codes in a billing UI, which must be paired with a primary procedure.
Resolving a tree node a user clicked, whether it is a code or a heading.

Mistaken use

Do not strip or append modifiers in code. Send the five-character code. To price a code with modifiers, use /api/lookup/fee_schedule/get, which takes modifiers as a separate parameter.
Do not treat a 404 as "not a real CPT code". It means the curated codebook does not hold it. To price a code the codebook does not hold, use /api/lookup/fee_schedule/get.
Do not use get to find codes by description. Use /api/lookup/cpt/search.

Debugging

Capture request_id. Present in every response body.
400 ValidationError naming code. The message says whether the value carried a modifier, looked like a HCPCS Level II code, or was not code-shaped.
404 NotFound for a code you know is valid. It is outside the curated codebook. Browse the codebook with /api/lookup/cpt/tree.
add_on and category missing. The value was a structural key, not a code; only codes carry them.

Rate limits

See rate-limits.md for the current per-consumer limits.

lookup-cpt-search.md — find codes by descriptor or code prefix.
lookup-cpt-tree.md — browse the codebook's sections and headings.
lookup-fee_schedule-get.md — the workers' compensation maximum for a code.
lookup-icd10cm-get.md — the same record shape for diagnosis codes.
lookup-naics-get.md, lookup-regulations-get.md — the other lookup resources' single-record operations.
authentication.md, errors.md, rate-limits.md, conventions.md — cross-cutting contract rules.

Change history

Date	Change
2026-10-14	Initial publication.
2026-10-14	The engine assigns every request ID; an `X-Request-ID` request header is not used.

Summary​

Endpoint​

Authentication​

Request​

Headers​

Path parameters​

Query parameters​

Body​

Response​

Success — 200 OK​

Response fields​

Status codes​

Examples​

curl​

A structural key from tree​

Python (requests)​

Node.js (native fetch)​

TypeScript​

Error scenarios​

Modifier suffix​

HCPCS Level II code​

Valid CPT code outside the codebook​

Intended use​

Mistaken use​

Debugging​

Rate limits​

Related​

Change history​

Summary

Endpoint

Authentication

Request

Headers

Path parameters

Query parameters

Body

Response

Success — `200 OK`

Response fields

Status codes

Examples

curl

A structural key from tree

Python (`requests`)

Node.js (native `fetch`)

TypeScript

Error scenarios

Modifier suffix

HCPCS Level II code

Valid CPT code outside the codebook

Intended use

Mistaken use

Debugging

Rate limits

Related

Change history