> ## Documentation Index > Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```bash theme={null} POST https://{your_api_url}/v1/codify ``` ### Required headers ```http theme={null} Content-Type: application/json Authorization: Bearer YOUR_API_KEY ``` ### Optional headers ```http theme={null} 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 ```json theme={null} { "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) ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "medical_note": "Patient with diabetes...", "model": "high-quality" } ``` *** ## Response structure ### Success response (HTTP 200) ```json theme={null} { "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) ```json theme={null} { "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 ```python theme={null} # 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: ```python theme={null} 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:** ```python theme={null} 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: ```python theme={null} 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: ```python theme={null} 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](/sofia/en/api/operations#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 Real requests and responses Error responses and how to handle them API authentication and headers Complete API specification