AI Documents

This reference covers the legacy v2 API at /api/v2.

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

Demographics, summary, and classification are included. Insurance, prior authorization details, and medical codes are configured independently for your developer account. New eligible AI API accounts have all three enabled; existing accounts keep their current options. Contact Medsender to change an option. Self-serve Fax API accounts do not have access to this endpoint.

Each upload saves the extraction options selected at that time. Changing an option affects future uploads; it does not change pending documents, saved results, or callback retries. Insurance uses the same unified extraction result as demographics.

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

ParameterRequiredDescription
fileYesPDF document only, up to 50 MB (52,428,800 bytes)
callback_urlYesURL to receive results when processing completes
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

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.

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

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

Get / List

JSON
{
  "aiResult": {
    "aiToken": "d9eabe46-7ba7-40a3-902f-1e383f636140",
    "patientName": "John Doe",
    "patientDob": "1990-01-15",
    "patientPhoneNumber": "+15550100001",
    "patientGender": "Male",
    "patientAddress": "123 Example Street, Anytown, CA 90210",
    "documentClassification": "Referral",
    "documentSummary": "Cardiology referral for routine evaluation.",
    "insurancePlanName": "Example Health PPO",
    "insurancePayer": "Example Insurance Co",
    "insuranceGroupNumber": "GRP-000001",
    "insuranceMemberId": "MEM000000001",
    "insuranceSubscriberName": "John Doe",
    "insuranceMemberNames": "John Doe",
    "icdCodesJson": [{"code": "R00.0"}, {"code": "I10"}],
    "cptCodesJson": [{"code": "99213"}, {"code": "93000"}],
    "hcpcsCodesJson": [],
    "completedAt": "2025-01-15T11:00:00.000Z",
    "errorDetails": null
  }
}
{
  "aiResult": {
    "aiToken": "d9eabe46-7ba7-40a3-902f-1e383f636140",
    "patientName": "John Doe",
    "patientDob": "1990-01-15",
    "patientPhoneNumber": "+15550100001",
    "patientGender": "Male",
    "patientAddress": "123 Example Street, Anytown, CA 90210",
    "documentClassification": "Referral",
    "documentSummary": "Cardiology referral for routine evaluation.",
    "insurancePlanName": "Example Health PPO",
    "insurancePayer": "Example Insurance Co",
    "insuranceGroupNumber": "GRP-000001",
    "insuranceMemberId": "MEM000000001",
    "insuranceSubscriberName": "John Doe",
    "insuranceMemberNames": "John Doe",
    "icdCodesJson": [{"code": "R00.0"}, {"code": "I10"}],
    "cptCodesJson": [{"code": "99213"}, {"code": "93000"}],
    "hcpcsCodesJson": [],
    "completedAt": "2025-01-15T11:00:00.000Z",
    "errorDetails": null
  }
}

Response Fields

The aiResult object contains extracted information:

FieldDescription
aiTokenUnique identifier for this AI document request
documentClassificationDocument type: "Referral", "Lab Result", "Pathology Report", "Prior Authorization", "Imaging Result", "Pharmacy Request", "Consult Note", "Discharge Summary", or "Treatment Consent". Other classifications return "Unable to classify document".
documentSummaryAI-generated summary of the document contents
patientNameFull patient name extracted from document
patientDobPatient date of birth (YYYY-MM-DD)
patientPhoneNumberPatient phone number
patientGenderPatient gender
patientAddressPatient address
insurancePlanNamePrimary insurance plan name
insurancePayerPrimary insurance payer/company
insuranceGroupNumberInsurance group number
insuranceMemberIdInsurance member ID
icdCodesJsonArray of ICD codes: [{"code": "I10"}, ...]
cptCodesJsonArray of CPT codes: [{"code": "99213"}, ...]
hcpcsCodesJsonArray of HCPCS codes
authorizationNumberPrior authorization number
authorizationFromDateAuthorization start date (YYYY-MM-DD)
authorizationToDateAuthorization end date (YYYY-MM-DD)
authorizationNumberOfVisitsAuthorized visit count (integer)
authorizationDescriptionExtracted authorization description
completedAtWhen processing completed (ISO 8601)
errorDetailsError message if processing failed, otherwise null

Authorization fields are included only for documents submitted with authorization extraction enabled; missing information is null. The legacy test integration retains its "unavailable in TEST environment" placeholders. Earlier documents keep their original response fields. Insurance and code fields retain their existing names and may be null when extraction is disabled or no value is found. Medical-code extraction includes ICD-10, CPT, and HCPCS together.

The callback POST keeps its existing AiDocumentDetails form field containing JSON with an aiResult object and camelCase field names. The added authorization fields follow the same format.