Request & Response Structure

Complete guide to Codify API requests and responses: ICD-10 medical coding with AI-powered analysis

The Codify API provides AI-powered ICD-10 medical coding services. It processes clinical notes or PDF files and returns structured medical coding assessments with confidence scores and justifications.

---

Request structure

Endpoint

POST https://{your_api_url}/v1/codify

Required headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Optional headers

x-doctor: dr_123      (for tracking)
x-patient: pt_456     (for tracking)

Request body structure

The medical_note field is required. You can optionally include a pdf_file for additional context:

Required: Text Input

{
  "medical_note": "Patient presents with Type 2 Diabetes Mellitus. Current medications: Metformin 500mg BID, Glipizide 5mg QD. Blood glucose levels stable. No complications noted. HbA1c: 6.8%.",
  "model": "balanced"
}

Optional: PDF Input (for additional context)

{
  "pdf_file": {
    "type": "file",
    "source_type": "base64",
    "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXI...",
    "mime_type": "application/pdf",
    "filename": "medical_note.pdf"
  },
  "model": "high-quality"
}

---

Required fields

medical_note (string, REQUIRED)

Clinical narrative text to process for ICD-10 coding. This field is always required.

Examples:

• “Patient admitted with acute myocardial infarction”
• “Type 2 Diabetes Mellitus, controlled with oral medications”
• “Diabetic patient with poor glycemic control, HbA1c 9.2%”

Constraints:

• Maximum size: 50 KB (~25,000 words)
• UTF-8 encoding
• Always required

pdf_file (object, optional)

Optional PDF file object for providing additional context or supporting documents.

Structure:

{
  "type": "file",
  "source_type": "base64",
  "data": "JVBERi0xLjQK...",
  "mime_type": "application/pdf",
  "filename": "medical_report.pdf"
}

Field constraints:

• type: Must be "file" (validated)
• source_type: Must be "base64" (validated)
• data: Base64 encoded PDF content (max 5MB decoded)
• mime_type: Must be "application/pdf" (validated)
• filename: String (required)
• Optional - can be provided alongside medical_note for additional context

---

Optional fields

model (string, optional)

AI model quality level selection for processing.

Available options:

• "fast" - Fastest processing with good accuracy (recommended for high-volume)
• "balanced" - Balance between speed and accuracy (default)
• "high-quality" - Highest accuracy with slower processing (recommended for complex cases)

Default: "balanced" if not specified

Example:

{
  "medical_note": "Patient with diabetes...",
  "model": "high-quality"
}

---

Response structure

Success response (HTTP 200)

{
  "final_code_assessments": [
    {
      "code": "E11.9",
      "description": "Type 2 diabetes mellitus without complications",
      "justification": "The note documents Type 2 Diabetes without mention of decompensation or complications; corresponds to E11.9 (DM2 without complications).",
      "confidence_percent": 92.4
    },
    {
      "code": "Z79.84",
      "description": "Long term (current) use of oral hypoglycemic drugs",
      "justification": "The patient uses metformin and glipizide chronically; both are oral antidiabetic drugs.",
      "confidence_percent": 96.1
    }
  ],
  "discarded_code_assessments": [
    {
      "code": "E10.9",
      "description": "Type 1 diabetes mellitus without complications",
      "justification": "Discarded because the note clearly specifies Type 2 Diabetes, not type 1.",
      "confidence_percent": 15.2
    }
  ],
  "run_id": "1ef8e0d4-7890-6b3c-8f90-abcdef123456"
}

Error response (HTTP 4xx/5xx)

{
  "success": false,
  "error": "Bad Request",
  "details": "Either medical_note or pdf_file must be provided"
}

---

Response fields explained

final_code_assessments (array)

Array of approved ICD-10 code assessments selected by the AI.

Each assessment contains:

• code (string): ICD-10 medical code (e.g., “E11.9”)
• description (string): Medical description of the code
• justification (string): AI reasoning for code selection
• confidence_percent (number): Confidence score (0-100)

discarded_code_assessments (array)

Array of considered but rejected code assessments. Shows the AI’s decision-making process and codes that were evaluated but not included.

Same structure as final_code_assessments

run_id (string)

Unique identifier (UUID) for this codification run.

Uses:

• Tracking and auditing
• Debugging issues
• Correlating with backend logs
• Support requests

---

Special cases

Very long input

If your clinical text exceeds 50KB or PDF exceeds 5MB:

Option 1: Split into multiple calls

# Process by sections
sections = split_into_sections(long_text)
results = []
for section in sections:
    result = codify(section)
    results.append(result)

Option 2: Compress and optimize

• For text: Remove unnecessary whitespace and formatting
• For PDFs: Compress PDF before encoding, remove non-essential pages

Option 3: Request enterprise limits Contact your sales representative for plans with higher limits.

PDF file encoding

To encode a PDF file for the API:

import base64

def encode_pdf(file_path):
    """Encode a PDF file to base64"""
    with open(file_path, 'rb') as file:
        pdf_bytes = file.read()
        base64_data = base64.b64encode(pdf_bytes).decode('utf-8')
    
    return {
        "type": "file",
        "source_type": "base64",
        "data": base64_data,
        "mime_type": "application/pdf",
        "filename": file_path.split('/')[-1]
    }

# Usage
pdf_file = encode_pdf("medical_report.pdf")
payload = {"pdf_file": pdf_file}

Text preprocessing

Optional but recommended:

def clean_clinical_text(text):
    """Cleans clinical text for better processing"""
    # Remove excessive line breaks
    text = re.sub(r'\n{3,}', '\n\n', text)
    
    # Normalize spaces
    text = re.sub(r'\s+', ' ', text)
    
    # Remove control characters
    text = ''.join(char for char in text if char.isprintable() or char in '\n\t')
    
    return text.strip()

---

Request optimization

Batch processing

For processing multiple notes, send parallel requests:

import concurrent.futures

def codify_note(note_text):
    """Process a single medical note"""
    return requests.post(
        f"{API_URL}/v1/codify",
        json={"medical_note": note_text},
        headers=headers
    ).json()

def process_batch(notes, max_workers=10):
    """Process multiple notes in parallel"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = [executor.submit(codify_note, note) for note in notes]
        results = []
        for future in concurrent.futures.as_completed(futures):
            results.append(future.result())
    return results

# Usage
notes = ["Patient with diabetes...", "Patient with pneumonia..."]
results = process_batch(notes)

Handling confidence scores

Filter results based on confidence thresholds:

def filter_high_confidence(response, threshold=80):
    """Filter codes with confidence above threshold"""
    return [
        assessment for assessment in response['final_code_assessments']
        if assessment['confidence_percent'] >= threshold
    ]

# Usage
result = codify_note("Patient with diabetes...")
high_confidence_codes = filter_high_confidence(result, threshold=85)

---

Limits and restrictions

See Complete limits and quotas for detailed information.

Main limits:

• Maximum medical_note size: 50 KB (~25,000 words)
• Maximum pdf_file size: 5 MB (decoded)
• Processing timeout: 10 minutes (600 seconds)
• Rate limit: Varies by customer plan

---

Next steps

View examples

Real requests and responses

Error handling

Error responses and how to handle them

Authentication

API authentication and headers

OpenAPI Reference

Complete API specification