Lab Reports API Implementation Guide
This guide provides complete implementation details and best practices for integrating the Lab Reports API into your applications. For detailed API specifications and data types, refer to the API Reference.Authentication: The code examples in this guide focus on the lab report analysis functionality. For authentication implementation details, see the Authentication documentation. You’ll need to add Bearer token into the Authorization header to all API requests.
API Endpoints
The Lab Reports API provides three main endpoints for managing lab reports:POST /lab_reports
— Upload lab report documents for AI-powered analysisGET /lab_reports
— Retrieve a list of lab reportsGET /lab_reports/{lab_report_id}
— Retrieve a specific lab report by ID
Document Preparation
For optimal document capture guidelines, see the Document Guidelines in the API overview.POST Request Body
Processing Modes
The processing mode is controlled by thewait_on_process
parameter. The API supports two processing modes, each suited for a different use case:
Asynchronous Processing
Returns immediately and processes the document in the background. Ideal for user-facing applications where immediate feedback is important. See the Asynchronous Processing Guide for complete implementation details, webhook configuration, and code examples.Synchronous Processing
Waits for complete analysis before responding. Best for batch processing, server-to-server integrations, or when you can handle longer response times: Request:Response Body
Processing Status
Analysis of the lab report progresses through these states:- pending — Analysis has been queued
- processing — AI model is actively analyzing the document
- completed — Analysis finished successfully with results
- failed — Processing failed due to unreadable content or technical issues
status
field.
status
field with values completed
or failed
only. Always handle different response statuses in your application logic.
Error Scenarios
Processing Failures
These occur when the API successfully receives your request but the AI analysis fails. The response will have HTTP 200 status with"status": "failed"
.
When status
is failed
, check the parsing_error
field for specific details:
- Document not a lab report: Document contains non-medical content
- Poor document quality: Blurry, dark, or low-resolution images/scans
- Unreadable text: OCR could not extract reliable text
Request Errors
These occur when there’s an issue with the request itself, returning non-200 HTTP status codes before analysis begins. For HTTP status code errors (400, 401, 422, etc.) and general API error handling, see the Error Handling documentation.Retrieving Results
Getting Results
For asynchronous processing, use webhooks for real-time notifications. See the Asynchronous Processing Guide for complete webhook implementation details. If webhooks are not yet available, you can check status using theGET /lab_reports/{lab_report_id}
endpoint.
Best Practices
1. Choose the Right Processing Mode
- Asynchronous: For user-facing applications, mobile apps, and when you want immediate feedback
- Synchronous: For batch processing, server-to-server integrations, and when you can handle longer response times
2. Implement Proper Error Handling
- Handle network errors gracefully
- Provide meaningful error messages to users
- Implement retry logic for transient failures
3. Optimize Document Upload
- Use high-resolution scans (300+ DPI) for better OCR results
- Validate document size and format before upload
- Show upload progress for large documents
Code Examples
Here are complete implementation examples in multiple programming languages:POST /lab_reports
API Reference.