# POST Requests

The direct AutoCoder API is asynchronous. Submit a coding task with a `POST`. The response returns a task `id`. Then [poll for the result](./get-request) with a `GET`.

## Endpoint

| Field | Value |
| --- | --- |
| Endpoint | `https://services.hank.ai/autocoding/v1/tasks/` |
| Method | `POST` |
| API key header | `x-api-key` |

## Request body

The request carries the clinical documents under `request.job.input.entities`, plus the patient, provider, and schedule context the coder uses. Send every field you have. The anesthesia fields in `schedule` drive modifier and qualifying-circumstance decisions, so omitting them degrades coding quality.

```json
{
  "Name": "some_blank_name",
  "request": {
    "service": "<reference to service>",
    "job": {
      "id": "your-internal-id",
      "input": {
        "entities": [
          {
            "inputType": "text",
            "lastModifiedTime": "Mon Nov 02 12:56:49 EST 2020",
            "noteType": "SurgeonProcedureNote",
            "content": "The document text for the type named in inputType"
          }
        ]
      },
      "patient_info": {
        "guarantor": [
          {
            "address": [
              { "city": "City", "state": "State", "street1": "Street", "street2": "", "zip": "Zip" }
            ],
            "first": "First",
            "fullName": "Full",
            "last": "Last",
            "middle": "Middle",
            "phone": [{ "number": "number" }],
            "relationship": "relationship to patient"
          }
        ],
        "insurance": [
          {
            "address": { "city": "City", "state": "State", "street1": "Street", "street2": "", "zip": "Zip" },
            "company": "company",
            "groupId": "group",
            "phone": "phone",
            "phoneExt": "",
            "policyId": "policy",
            "priority": "priority"
          }
        ],
        "patient": {
          "accn": "account number",
          "address": [
            { "city": "city", "state": "state", "street1": "street", "street2": "", "zip": "zip" }
          ],
          "dob": "dob",
          "encn": "encounter",
          "first": "first",
          "fullName": "full",
          "last": "last",
          "middle": "middle",
          "mrn": "mrn",
          "phone": [{ "number": "phone number", "type": "home" }],
          "sex": "M"
        }
      },
      "provider": {
        "correlation_id": "internal ID",
        "facility": "facility name",
        "name": "HBS"
      },
      "schedule": {
        "anType": "anesthesia type",
        "anesthesiaStaff": "staff",
        "anesthesiologist": "anesthesiologist",
        "asa": "3",
        "date": "date",
        "difficultIntubation": "No",
        "emergent": "0",
        "endTime": "end time",
        "postNote": "1",
        "preNote": "1",
        "recSigned": "1",
        "room": "room number",
        "startTime": "start time",
        "surgeon": "name",
        "surgeonNPI": "NPI Number"
      },
      "meta": {
        "squash_icd": false,
        "note_classification": true
      }
    }
  }
}
```

### entities

Each entity carries one clinical document. `content` holds the document text. `noteType` names the kind of document. The accepted values are:

`SurgeonProcedureNote`, `AnesthesiaProcedureNote`, `AnesthesiaPreoperativeNote`, `DiagnosisDescription`, `SurgeryDescription`, `AnesthesiaProcedureNote_AirwayPlacement`, `AnesthesiaProcedureNote_LaborEpidural`, `AnesthesiaProcedureNote_ArterialLine`, `AnesthesiaProcedureNote_NerveBlock`, `AnesthesiaProcedureNote_EpiduralCatheterNonOB`, `AnesthesiaProcedureNote_CentralLine`

Send more than one entity when the case has more than one document.

### patient_info

| Block | Fields | Notes |
| --- | --- | --- |
| `patient` | `accn`, `address[]`, `dob`, `encn`, `first`, `fullName`, `last`, `middle`, `mrn`, `phone[]`, `sex` | `sex` is `M` or `F`. `phone[].type` names the number kind. |
| `guarantor[]` | `address[]`, `first`, `fullName`, `last`, `middle`, `phone[]`, `relationship` | One entry per guarantor. |
| `insurance[]` | `address`, `company`, `groupId`, `phone`, `phoneExt`, `policyId`, `priority` | One entry per policy, ordered by `priority`. |

### provider

| Field | Notes |
| --- | --- |
| `correlation_id` | Your internal ID for this request. The response echoes it back so you can match results to your records. |
| `facility` | The facility name. |
| `name` | The provider or billing-service name. |

### schedule

The schedule block carries the case context. The anesthesia fields drive modifier and qualifying-circumstance coding:

| Field | Values | Notes |
| --- | --- | --- |
| `anType` | text | The anesthesia type. |
| `anesthesiaStaff` | text | The anesthesia staff on the case. |
| `anesthesiologist` | text | The anesthesiologist of record. |
| `asa` | `1` to `6` | The ASA physical status. Drives the P1 to P6 modifiers. |
| `date` | date | The date of service. |
| `difficultIntubation` | `Yes` / `No` | Difficult intubation flag. |
| `emergent` | `0` / `1` | Emergency flag. Drives 99140 qualifying-circumstance coding. |
| `startTime`, `endTime` | time | Anesthesia start and end. Drive time units. |
| `preNote`, `postNote`, `recSigned` | number | Pre-note, post-note, and record-signed indicators. |
| `room` | text | The room. |
| `surgeon` | text | The surgeon of record. |
| `surgeonNPI` | NPI | The surgeon NPI. |

### meta

| Flag | Effect |
| --- | --- |
| `squash_icd` | `true` collapses duplicate ICD codes across line items. |
| `note_classification` | `true` runs note classification on the submitted documents before coding. |

## Response

The POST response returns the task id to poll:

```json
{
  "id": "<id>",
  "metadata": {
    "apiVersion": "1.0",
    "timeStamp": "timestamp",
    "apiKey": "<your-api-key>"
  }
}
```

Poll the `id` with a [GET request](./get-request) until the task state is `Completed`.