API: Quick start

Get started with the SofIA Codify API in minutes with a simple request example

Prerequisites

API Token

We provide it when contracting the service

Endpoint

Production or development URL

Tool for making HTTP requests

Postman, curl, or your favorite language

---

Your first API call

Basic example with curl

curl -X POST "https://{your-endpoint}/v1/codify" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "x-doctor: dr_123" \
  -H "x-patient: pt_456" \
  -d '{
    "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"
  }'

Expected response

{
  "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, supporting long term use of oral hypoglycemic drugs.",
      "confidence_percent": 96.1
    }
  ],
  "discarded_code_assessments": [],
  "run_id": "1ef8e0d4-7890-6b3c-8f90-abcdef123456"
}

Congratulations! You have coded your first clinical note with AI-powered ICD-10 medical coding!

---

Request breakdown

Mandatory headers

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json

Optional headers

Visit Authentication for traceability header configuration.

Request body

You must provide either medical_note OR pdf_file (mutually exclusive):

Field	Required	Description
medical_note	Yes*	The clinical text to code (max 50KB)
pdf_file	Yes*	PDF file object with base64 encoded data (max 5MB decoded)
model	No	AI model quality level: "fast", "balanced" (default), or "high-quality"

*One of medical_note or pdf_file is required, but not both.

---

Examples in different languages

Python

import requests

url = "https://{your-endpoint}/v1/codify"
headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE",
    "Content-Type": "application/json",
    "x-doctor": "dr_123",
    "x-patient": "pt_456"
}

payload = {
    "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"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Final codes: {len(result['final_code_assessments'])}")
for assessment in result['final_code_assessments']:
    print(f"  {assessment['code']}: {assessment['description']} ({assessment['confidence_percent']}%)")
print(f"Run ID: {result['run_id']}")

---

Available environments

Visit Environment configuration for detailed URLs and features.

---

Next steps

1. View complete structure

All available fields

2. View PDF file format

How to send PDF files for coding

3. View advanced examples

Real use cases (billing datasets, structured notes, etc.)

4. Error handling

What to do when something fails