---
title: "Code Chart To Cpt"
method: POST
path: "/api/v1/cpt/code"
tags: ["cpt"]
---

# Code Chart To Cpt

`POST /api/v1/cpt/code`

## Request

- Base URL: `https://api.accurecord.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.accurecord.io/api/v1/cpt/code`
- Auth: none declared

Code the procedures documented in a chart, then scrub the resulting claim.

Five stages: LLM procedure-mention extraction → deterministic retrieval → batched LLM
disambiguation → deterministic modifier proposal → deterministic verification.

⚠ **Neither LLM call can produce a code.** Stage 1 raises on a code-shaped token; Stage 3
chooses from the list retrieval built and verified against the code set. The codes this
endpoint can emit are exactly the codes retrieval found — that is a property of the
wiring, not of the prompts.

⚠ **Read `result_state` before `lines`.** An empty line list means one of several very
different things, and `documentation_gap` (a chart problem you can act on) is not
`retrieval_unavailable` (our corpus is unbuilt).

⚠ **`candidate_modifiers` are prompts, not decisions.** A modifier under
`applied_modifiers` follows from a documented axis and a CMS indicator. One under
`candidate_modifiers` is permitted by the fee schedule but needs the note to support it,
and the verification below was run WITHOUT it applied. **59 and 25 are never proposed at
all** — they assert clinical facts only the documentation establishes.

**Requires Pro or Enterprise tier, an executed BAA, and PHI activation.**

## Headers

- `x-api-key` string, nullable

## Request body

- CptCodeRequest
  - `chart_text` string, required: Operative note or encounter documentation. ⚠ PHI.
  - `practice_setting` string
  - `dos` string, date, nullable: Date of service
  - `prior_procedures` object[]
  - `patient_age` integer, nullable
  - `patient_sex` string, nullable
  - `em_family` string, nullable: Level the visit's E/M too, e.g. 'office_established'. ⚠ Required from you rather than inferred — new-vs-established and office-vs-hospital are facts about the encounter a note frequently does not state. Adds one LLM call.
  - `version` integer, nullable
  - `payer_type` 'medicare_ffs' | 'medicare_advantage' | 'medicaid' | 'commercial', nullable: Who pays. Optional. Known: Medicare's dispositions are enforced for medicare_ffs (PFS N/B and HCPCS coverage I/M/S become blocking errors); for medicare_advantage Medicare's coding and coverage are stated as warnings, because the plan's own billing instructions decide; for medicaid/commercial a Medicare status is stated but never generalised. Absent: the payer is unresolved: every Medicare disposition is a warning that says so, and a line whose code depends on the payer is flagged, not billed as sent.
  - `payer_state` string, nullable: Two-letter state of the Medicaid programme. Only with payer_type=medicaid.
  - `diagnoses` string[], nullable: The claim's Box 21 diagnoses, ICD-10-CM, lettered A-L in this order. Optional. Codes are checked as billable for the fiscal year of the date of service. Pointers are CHART-LINKED ONLY: a line points at a diagnosis only where the chart explicitly ties that service to it (quoted verbatim), otherwise the line carries the review item 'dx pointer not documented' — never a default.

## Response `200`

Successful Response

- object

## Other responses

- `400`: Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.
- `401`: Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.
- `403`: Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.
- `404`: Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.
- `412`: A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.
- `422`: Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).
- `429`: Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.
- `500`: Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.
- `503`: The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.

---

[API](https://skmtc.dev/accurecord/apis/icd-10-coding-api.md) · [All operations](https://skmtc.dev/accurecord/apis/icd-10-coding-api/llms.txt) · [OpenAPI document](https://skmtc.dev/accurecord/apis/icd-10-coding-api/revisions/b1e12ce06ba5?raw)