When a document ends without a result, Lab Data API sends a notification to your Notification Webhook. Each notification includes the document_id and a message that says what to do, so check your notifications first.
After an individual upload, Lab Data API returns 200 OK with a document_id. After a batch upload, it returns a batch ID and a document_id with an upload URL for each document. Every document is processed asynchronously. Results arrive only through your Data Webhook, and notifications only through your Notification Webhook: there is no endpoint to check the processing status. For the request and response codes, see the Lab Data documentation.
Store the document_id of each document. The same value arrives in the result as laboratory_data.metadata.document_id_string, and in every notification.
Notifications when a document ends without a result
To receive notifications, configure your Notification Webhook in the ROOK Portal under Set up > Webhook > Notification Webhook. Without it, a document that ends without a result sends nothing.
Notification | What it means |
document_failed | The document couldn't be processed and won't be retried automatically, for example because the sample collection date and time are missing or unreadable. |
document_duplicate | Your organization had already submitted a file with exactly the same content, so it isn't processed again. |
document_expired | Batch uploads only. The file of a document didn't arrive within 24 hours. |
document_rejected | Batch uploads only. The file doesn't meet the requirements: format, size, page count or time zone. The message says which one. |
Processing also recovers on its own where it can. If an extraction attempt fails, ROOK retries it automatically before marking the document as failed. A document that hasn't moved for more than an hour is closed as failed and sends its document_failed notification, so you aren't left waiting for a result that won't arrive.
A document_expired notification usually arrives within 2 hours of the 24-hour deadline. If many documents expire together, the notifications are spread over several hours.
Common situations
Situation | Possible cause | What to do |
No result and no notification arrive | Your Notification Webhook is not configured, so notifications can't reach you. | Configure it in the ROOK Portal under Set up > Webhook > Notification Webhook. |
No result and no notification arrive yet after a batch upload | The batch is still being processed. A batch of 1,000 documents takes about 1 hour, and individual uploads are processed first. | Wait before submitting again. The time is approximate and depends on factors such as connection speed and document size and format. |
A biomarker from the document is missing in panels_array | The biomarker did not pass validation. | Look for it in rejected_biomarkers_array and check its reason_string. |
A biomarker has plausibility_flag: true | The value is unusual or inconsistent with a related biomarker. | Review the value against the original document before using it. This flag is included in ROOK JSON, not in FHIR R4. |
400 Bad Request with Unsupported file type | The file content is not PDF, JPEG, or PNG, for example HEIC, WebP, GIF, TIFF, or Word. ROOK identifies the file type from its content, not from its extension. | Convert the file to PDF, JPEG, or PNG. In a batch upload, this arrives as a document_rejectednotification. |
403 Forbidden | The credentials do not match the client_uuid in the path, or Lab Data API is not activated in this environment. | |
429 Too Many Requests with a Retry-After header | Your client already has 150 individual documents in progress. The file was not stored. | Wait the time in Retry-After and submit the document again. |
An individual upload is rejected because of the user_id | The user_id doesn't exist for your organization. Nothing is stored. | Use a user_id that already exists for your organization. |
A batch upload request is rejected | A user_id in the list doesn't exist, or another field is invalid. No document is created. | The response gives the position and field with the error. Fix it and send the list again. |
A batch upload request would exceed the limit | Your client can have up to 1,000 pending documents across all its batches. No document is created. | The response says how many documents you can still declare. |
An upload URL expired | Each upload URL works for up to 60 minutes. | Request a new URL for the same document with the batch ID. The document's 24-hour deadline doesn't change. |
When you contact ROOK Support about a document, always include the document_id returned at submission.
Duplicate documents
A document is identified as a duplicate when your organization submits a file with exactly the same content as a previous submission, even for a different user_id. Duplicates are not processed again and do not generate a new Data Webhook. Lab Data API sends a document_duplicate notification instead.
A document that failed is not treated as a duplicate: you can submit it again.
Go-live checklist
Before sending production traffic, verify that:
Lab Data API is activated for your client_uuid in the environment you call, from your ROOK Portal or through the ROOK Support team. Sandbox and Production are activated separately.
Your backend sends requests with Basic authentication, using your client_uuid and secret_key. Never call Lab Data API from a web browser or a mobile app, so your credentials are not exposed to end users.
The client_uuid in the URL path matches the client_uuid of your credentials.
Your backend sends individual uploads as multipart/form-data, with both file and timezone. The timezone value is an ISO-8601 UTC offset, from -14:00 to +14:00, or Z for UTC.
If you use batch uploads, your backend uploads each file within 60 minutes of receiving its URL, and within 24 hours of declaring the document.
Your backend handles every documented response code, including 429 with Retry-After.
Your Data Webhook is registered, reachable over HTTPS, and routes data_structure: "lab_result_event".
Your Notification Webhook is configured in the ROOK Portal under Set up > Webhook > Notification Webhook.
You store the document_id of each document to correlate it with its result and its notifications.
You have tested PDF, JPEG, and PNG documents, and every document shows a legible sample collection date and time. You can test up to 10 documents in the ROOK Portal testing space without integrating the API; these tests aren't billed.