How medical coding works
Medical coding follows the same reasoning a professional coder uses. It runs as an asynchronous job: you start a job, the service processes it in the background, and you retrieve the results when the job completes. This model suits coding workflows where documentation is finalized first and coded afterward, and it lets you submit many jobs without holding a connection open.
From documentation to codes
After you call StartMedicalCodingJob, the medical coding service processes the job in the following steps. Your application doesn’t run or control these steps. It submits the job and reads the result.
-
Read the encounter. The service reads the clinical documentation together with the encounter context and patient context you provide.
-
Extract the clinical facts. It identifies the conditions addressed, the procedures performed, and the services rendered.
-
Determine the E/M level. For visits, it assesses the problems addressed and the risk of patient management documented in the note, following MDM guidelines, and assigns the E/M level the documentation supports.
-
Assign codes. It assigns ICD-10-CM codes to diagnoses and CPT codes to procedures and services, adding modifiers where the documentation requires them. It uses the most specific code the documentation supports.
-
Link and support. It links each CPT code to the diagnoses that establish its medical necessity, attaches the note passages that support each code, and assigns each code a confidence score.
-
Deliver. It writes the result as structured JSON to your S3 output location, and
GetMedicalCodingJobreturns the location of the file.
The job lifecycle
| Step | What happens | Your role |
|---|---|---|
|
1. Submit |
You call |
Provide the text and output path, and include encounter and patient context whenever you have it. |
|
2. Process |
The service derives the code set from the documentation, as described in From documentation to codes, and writes the results file to your S3 location. |
None. Processing runs in the background. |
|
3. Retrieve |
You call |
Poll for completion, then read the results file. |
The quality of the suggested codes depends on what you provide at the submit step. The encounterContext and patientContext fields are optional, but they are important for optimal coding accuracy, because the visit type and the patient’s status and demographics change which codes apply. Include them whenever you have the data. See Medical coding inputs.
Job status
GetMedicalCodingJob returns the job’s current state in jobStatus. A job normally moves from SUBMITTED to IN_PROGRESS, and then to SUCCEEDED or FAILED. In rare cases, such as a service infrastructure issue that keeps a job from starting, a job can move directly from SUBMITTED to FAILED.
jobStatus
|
Meaning | What to do |
|---|---|---|
|
|
The job has been accepted and is queued. |
Keep polling. |
|
|
The service is analyzing the documentation and generating codes. |
Keep polling. |
|
|
The job completed. The results file is in your S3 output location, and the response gives its URI. |
Read the results. See Medical coding outputs. |
|
|
The job did not complete. |
Check |
Tip
A primary care note typically completes in about 35 seconds. Wait about 10 seconds before the first GetMedicalCodingJob call, then back off exponentially to a maximum interval of 30 seconds. Each response also includes creationTime and updatedTime, so you can see how long a job has been running.
Some problems are caught before a job is created. StartMedicalCodingJob validates the input and checks the S3 and AWS KMS permissions first. If a check fails, the call returns an error, such as ValidationException or AccessDeniedException, and no job is created.
Idempotent submissions
StartMedicalCodingJob accepts an optional clientToken, a unique, case-sensitive identifier you provide. If a request is retried with the same clientToken (for example, after a network timeout), the service treats it as the same job instead of starting a duplicate. Use a clientToken whenever your application might retry a submission.
