# Medical coding inputs
<a name="mc-inputs"></a>

A medical coding job requires the clinical documentation and an output location in the request body, and your domain ID in the request path. Two optional context objects describe the encounter and the patient.


| Parameter | Required | Purpose | 
| --- | --- | --- | 
|  `text`  | Yes | The clinical documentation to generate codes from | 
|  `outputDataConfig.s3OutputPath`  | Yes | The S3 location where results are written | 
|  `encounterContext`  | No | Context about the encounter: type, reason, and timing | 
|  `patientContext`  | No | Context about the patient: sex, status, date of birth, and insurance | 
|  `domainId` (request path) | Yes | Your Amazon Connect Health domain ID: 20 to 25 characters, beginning with `hai-` or `dom-`  | 
|  `clientToken`  | No | Case-sensitive idempotency token for safe retries. See [Idempotent submissions](mc-how-it-works.md#mc-idempotency). | 

**Topics**
+ [Example request](#mc-input-example)
+ [Clinical documentation (`text`)](#mc-input-text)
+ [Encounter context (`encounterContext`)](#mc-input-encounter-context)
+ [Patient context (`patientContext`)](#mc-input-patient-context)
+ [How context affects code selection](#mc-input-context-impact)
+ [Output location (`outputDataConfig.s3OutputPath`)](#mc-input-output-location)
+ [Validation patterns](#mc-input-patterns)

## Example request
<a name="mc-input-example"></a>

The following `StartMedicalCodingJob` request body uses fictional clinical text and includes both context objects.

```
{
  "clientToken": "encounter-20261003-000123",
  "text": "Established patient seen in clinic for follow-up of type 2 diabetes and essential hypertension. Blood pressure controlled on current regimen. A1c reviewed. Continue metformin and lisinopril. Return in 3 months.",
  "encounterContext": {
    "encounterType": "IN_PERSON",
    "encounterReason": "Follow-up of diabetes and hypertension",
    "afterHours": false
  },
  "patientContext": {
    "sex": "FEMALE",
    "status": "ESTABLISHED",
    "dateOfBirth": "1961-04-12",
    "insurance": "Medicare"
  },
  "outputDataConfig": {
    "s3OutputPath": "s3://amzn-s3-demo-bucket/medical-coding/"
  }
}
```

## Clinical documentation (`text`)
<a name="mc-input-text"></a>

Provide the clinical documentation to be analyzed. This can include encounter notes, clinical summaries, or other documentation that describes the patient’s conditions, procedures, and services rendered. The field must contain at least one non-whitespace character and can be up to 100,000 characters.

**Tip**  
The more completely the documentation describes conditions, procedures, and clinical reasoning, the more accurate and better-supported the suggested codes. Documentation generated by [ambient documentation](ambient-documentation.md) is a natural input to medical coding.

## Encounter context (`encounterContext`)
<a name="mc-input-encounter-context"></a>

Describes the clinical encounter. This field is optional, but it is important for optimal coding accuracy, because the type and timing of the visit change which codes apply. Include it whenever you have the data. See [How context affects code selection](#mc-input-context-impact).


| Field | Type | Allowed values | Notes | 
| --- | --- | --- | --- | 
|  `encounterType`  | String |  `TELEHEALTH` or `IN_PERSON`  | The type of encounter | 
|  `encounterReason`  | String | Free text, up to 256 characters | Letters, digits, spaces, periods, commas, and hyphens only | 
|  `afterHours`  | Boolean |  `true` or `false`  | Whether the encounter occurred outside regular business hours | 

## Patient context (`patientContext`)
<a name="mc-input-patient-context"></a>

Describes the patient. This field is optional, but it is important for optimal coding accuracy, because the patient’s status, age, sex, and insurance change which codes apply. Include it whenever you have the data. See [How context affects code selection](#mc-input-context-impact).


| Field | Type | Allowed values | Notes | 
| --- | --- | --- | --- | 
|  `sex`  | String |  `MALE`, `FEMALE`, `NON_BINARY`, or `UNKNOWN`  | The patient’s sex | 
|  `status`  | String |  `NEW` or `ESTABLISHED`  | Whether the patient is new to the practice or established | 
|  `dateOfBirth`  | String |  `YYYY-MM-DD`  | ISO 8601 date, used to determine the patient’s age | 
|  `insurance`  | String | Free text | The patient’s insurance information | 

## How context affects code selection
<a name="mc-input-context-impact"></a>

Coding rules depend on facts about the encounter and the patient that the note alone may not state. The following table shows what each context field changes.


| Field | Why it matters in coding (examples) | 
| --- | --- | 
|  `patientContext.status`  | Office E/M codes are split into new-patient and established-patient families. The wrong status produces a code from the wrong family. | 
|  `encounterContext.encounterType`  | Depending on the payer, telehealth visits can require telehealth modifiers and different place-of-service reporting. | 
|  `encounterContext.afterHours`  | Services outside regular hours can qualify for additional after-hours service codes. | 
|  `encounterContext.encounterReason`  | The reason for the visit anchors the primary diagnosis. | 
|  `patientContext.dateOfBirth`  | Age determines age-banded codes, such as preventive visits, and age-related code edits. | 
|  `patientContext.sex`  | Some diagnosis and procedure codes are valid only for a specific sex. | 
|  `patientContext.insurance`  | The model aims to broadly follow common payer-specific coding patterns, but it doesn’t guarantee that codes match every payer’s billing practices. Medical coding is not a claim scrubber and doesn’t track or enforce individual payer policies. Apply your own payer rules before claim submission. | 

## Output location (`outputDataConfig.s3OutputPath`)
<a name="mc-input-output-location"></a>

The S3 path where the job writes its results, in the form `s3://bucket-name/optional/prefix/`, up to 1,024 characters. The bucket must exist. Medical coding writes the results file using the caller’s credentials, so the caller needs permission to write objects to this path. If the domain uses a customer managed AWS KMS key, the caller also needs permission to use that key. `StartMedicalCodingJob` checks these permissions before it creates the job. For the contents of the results file, see [Medical coding outputs](mc-outputs.md).

## Validation patterns
<a name="mc-input-patterns"></a>

The service validates the following values and returns a `ValidationException` when a value doesn’t match.


| Parameter | Pattern | Length | 
| --- | --- | --- | 
|  `domainId`  |  `(hai-\|dom-)[a-z0-9]+`  | 20 to 25 characters | 
|  `outputDataConfig.s3OutputPath`  |  `s3://[a-z0-9][\.\-a-z0-9]{1,61}[a-z0-9](/.*)?`  | Up to 1,024 characters | 
|  `encounterContext.encounterReason`  |  `[a-zA-Z0-9 .,-]+`  | Up to 256 characters | 
|  `patientContext.dateOfBirth`  |  `\d{4}-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])`  | 10 characters (`YYYY-MM-DD`) | 
|  `text`  | At least one non-whitespace character | Up to 100,000 characters | 
|  `clientToken`  | At least one non-whitespace character | No documented maximum |