AI Documents

Upload a file and receive extracted fields and classification when processing completes (via the endpoint response and your callback).

Run AI on a document

POST /ai_documents — Upload a document for AI extraction. Returns immediately with a token; results are sent to your callback URL when processing completes.

Request Parameters

Parameter	Required	Description
file	Yes	PDF or TIFF document to process
callback_url	Yes	URL to receive results when processing completes

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "callback_url=https://example.com/webhooks/ai" \
  "$API_BASE/ai_documents"

bash

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "callback_url=https://example.com/webhooks/ai" \
  "$API_BASE/ai_documents"

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "callback_url=https://example.com/webhooks/ai" \
  "$API_BASE/ai_documents"

List AI Documents

GET /ai_documents

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents" | jq

bash

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents" | jq

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents" | jq

Get AI Document

GET /ai_documents/:id where :id is the returned token.

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents/REPLACE_AI_TOKEN" | jq

bash

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents/REPLACE_AI_TOKEN" | jq

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/ai_documents/REPLACE_AI_TOKEN" | jq

Response Examples

Create

{
  "message": "AI Document Classification has initiated, callback will be sent upon completion.",
  "ai_token": "c4d5e6f7a8b9"
}

JSON

{
  "message": "AI Document Classification has initiated, callback will be sent upon completion.",
  "ai_token": "c4d5e6f7a8b9"
}

{
  "message": "AI Document Classification has initiated, callback will be sent upon completion.",
  "ai_token": "c4d5e6f7a8b9"
}

Get / List

{
  "ai_result": {
    "ai_token": "d9eabe46-7ba7-40a3-902f-1e383f636140",
    "patient_name": "John Doe",
    "patient_dob": "1990-01-15",
    "patient_phone_number": "+15550100001",
    "patient_gender": "Male",
    "patient_address": "123 Example Street, Anytown, CA 90210",
    "document_classification": "Referral",
    "document_summary": "Cardiology referral for routine evaluation.",
    "insurance_plan_name": "Example Health PPO",
    "insurance_payer": "Example Insurance Co",
    "insurance_group_number": "GRP-000001",
    "insurance_member_id": "MEM000000001",
    "insurance_subscriber_name": "John Doe",
    "insurance_member_names": ["John Doe"],
    "icd_codes_json": [{"code": "R00.0"}, {"code": "I10"}],
    "cpt_codes_json": [{"code": "99213"}, {"code": "93000"}],
    "hcpcs_codes_json": [],
    "completed_at": "2025-01-15T11:00:00.000Z",
    "error_details": null
  }
}

JSON

{
  "ai_result": {
    "ai_token": "d9eabe46-7ba7-40a3-902f-1e383f636140",
    "patient_name": "John Doe",
    "patient_dob": "1990-01-15",
    "patient_phone_number": "+15550100001",
    "patient_gender": "Male",
    "patient_address": "123 Example Street, Anytown, CA 90210",
    "document_classification": "Referral",
    "document_summary": "Cardiology referral for routine evaluation.",
    "insurance_plan_name": "Example Health PPO",
    "insurance_payer": "Example Insurance Co",
    "insurance_group_number": "GRP-000001",
    "insurance_member_id": "MEM000000001",
    "insurance_subscriber_name": "John Doe",
    "insurance_member_names": ["John Doe"],
    "icd_codes_json": [{"code": "R00.0"}, {"code": "I10"}],
    "cpt_codes_json": [{"code": "99213"}, {"code": "93000"}],
    "hcpcs_codes_json": [],
    "completed_at": "2025-01-15T11:00:00.000Z",
    "error_details": null
  }
}

{
  "ai_result": {
    "ai_token": "d9eabe46-7ba7-40a3-902f-1e383f636140",
    "patient_name": "John Doe",
    "patient_dob": "1990-01-15",
    "patient_phone_number": "+15550100001",
    "patient_gender": "Male",
    "patient_address": "123 Example Street, Anytown, CA 90210",
    "document_classification": "Referral",
    "document_summary": "Cardiology referral for routine evaluation.",
    "insurance_plan_name": "Example Health PPO",
    "insurance_payer": "Example Insurance Co",
    "insurance_group_number": "GRP-000001",
    "insurance_member_id": "MEM000000001",
    "insurance_subscriber_name": "John Doe",
    "insurance_member_names": ["John Doe"],
    "icd_codes_json": [{"code": "R00.0"}, {"code": "I10"}],
    "cpt_codes_json": [{"code": "99213"}, {"code": "93000"}],
    "hcpcs_codes_json": [],
    "completed_at": "2025-01-15T11:00:00.000Z",
    "error_details": null
  }
}

Response Fields

The ai_result object contains extracted information:

Field	Description
ai_token	Unique identifier for this AI document request
document_classification	Document type: "Referral", "Lab Result", "Prior Authorization", "Imaging Result", "Pharmacy Request", "Consult Note", "Discharge Summary", "Medical Records Request", or "Other"
document_summary	AI-generated summary of the document contents
patient_name	Full patient name extracted from document
patient_dob	Patient date of birth (YYYY-MM-DD)
patient_phone_number	Patient phone number
patient_gender	Patient gender
patient_address	Patient address
insurance_plan_name	Primary insurance plan name
insurance_payer	Primary insurance payer/company
insurance_group_number	Insurance group number
insurance_member_id	Insurance member ID
icd_codes_json	Array of ICD codes: [{"code": "I10"}, ...]
cpt_codes_json	Array of CPT codes: [{"code": "99213"}, ...]
hcpcs_codes_json	Array of HCPCS codes
completed_at	When processing completed (ISO 8601)
error_details	Error message if processing failed, otherwise null