{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Best Practices — Pathology — JondaX API Docs","description":"Best practices for integrating the JondaX Pathology module. Covers callback reliability, output format selection, payload type handling, API key security, status polling, and data retention.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"best-practices","__idx":0},"children":["Best Practices"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Quick tips:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Make sure your callback URL is reachable and responding before uploading files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If results don't arrive, check the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transformed Files"]}," page in the portal — your output may be there for download"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadId"]}," (shown after each upload) — support will ask for it if something goes wrong"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When in doubt, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@jonda.health"},"children":["support@jonda.health"]}," with your uploadId and a description of the issue"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-endpoint-reliability","__idx":1},"children":["Callback endpoint reliability"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure your endpoint is highly available and publicly reachable before configuring it in the Integration page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Respond with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," status code as fast as possible — process the payload asynchronously if needed. JondaX treats any non-2xx response as a failure and schedules a retry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["JondaX retries up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3 times"]}," (immediately, 30 min, 6 hrs). If all attempts fail the result is stored for 30 days — use the status polling endpoint to check delivery and contact support to retrieve a stored result."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log all incoming callback requests including headers and body for troubleshooting."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"always-verify-callback-authenticity","__idx":2},"children":["Always verify callback authenticity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every callback includes the authentication header name and value you configured on the Integration page. Reject any request that does not carry the expected header and value."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["FHIR JSON Inline"]}," callbacks, the metadata is delivered as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-JondaX-*"]}," request headers rather than in the body. Verify your chosen auth header is present alongside these headers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-both-content-type-values","__idx":3},"children":["Handle both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}," values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint must accept both content types depending on the configured payload type:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Payload type"},"children":["Payload type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Content-Type"},"children":["Content-Type"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inline (JSON)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inline (FHIR JSON)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/fhir+json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["File (all formats)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The file part within each multipart callback carries its own content-type:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Output format"},"children":["Output format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"File part Content-Type"},"children":["File part Content-Type"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HL7"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/hl7-v2"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR JSON"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR XML"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/fhir+xml"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSV"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text/csv"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parquet"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/octet-stream"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For File-type callbacks, always read the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," part first — it carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputFormat"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalTests"]}," without having to parse the result file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choosing-an-output-format","__idx":4},"children":["Choosing an output format"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Best for"},"children":["Best for"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON Inline"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Simple integrations — parse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Results[]"]}," directly from the request body"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JSON File"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same data as inline but delivered as a file attachment alongside metadata"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HL7"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EHR/LIS systems that already consume HL7 v2.3 messages"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR JSON"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR R4-compatible systems; inline delivery keeps the bundle as the raw body"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR XML"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["FHIR R4-compatible systems that require XML serialization"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSV"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Spreadsheet tools, ETL pipelines, or any tabular consumer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parquet"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Data warehouses, analytics pipelines, or high-volume result sets"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["CSV and Parquet use identical columns in the same order — switching between them requires no schema changes on your end."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-result-values","__idx":5},"children":["Handling result values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Results[].Result"]}," is always a string and can take several forms — handle all of them:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Numeric: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"17.00\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Qualitative: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"NEGATIVE\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"POSITIVE\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"NORMAL\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Flagged numeric: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"0.52 H\""]}," (value plus a flag character)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["With comparator: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"<0.1\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Empty string: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"\""]}," — result not detected or not available"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Similarly, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Low-Ref-Range"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["High-Ref-Range"]}," may be empty, numeric strings, or include a comparator prefix like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"<0.3\""]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-status-polling-as-a-safety-net","__idx":6},"children":["Use status polling as a safety net"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always store the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadId"]}," returned from each upload. If your callback endpoint was unreachable or you suspect a delivery issue, poll the status endpoint to check:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://app.jondax.eu/api/v1/status/:uploadId\nAuthorization: Bearer <JONDAX_API_KEY>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackDelivery.status"]}," — if it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exhausted"]},", contact support with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadId"]}," to retrieve the stored result before the 30-day retention window closes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"file-upload","__idx":7},"children":["File upload"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate file size (max 10 MB) and format on the client side before uploading to avoid unnecessary round trips."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supported formats: PDF, HL7, XML, JSON, CSV, Parquet, and Images (PNG, JPEG, HEIC, HEIF, GIF, AVIF, WEBP, BMP, TIFF)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use descriptive filenames with ASCII characters. Avoid special symbols or excessively long names."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-key-security","__idx":8},"children":["API key security"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the API key in environment variables or a secrets manager — never in client-side code or source control."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rotate the key immediately from the Integration page if it is exposed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the same API key consistently for uploads and status polling — the status endpoint enforces ownership and will return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," if the key does not match the one used to create the upload."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-retention","__idx":9},"children":["Data retention"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadId"]}," values and associated results are retained for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["30 days"]}," from the upload date. After expiry the record returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," and the data is permanently purged. Retrieve or store any results you need before the window closes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"environments","__idx":10},"children":["Environments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is currently no separate sandbox environment. Use your production API key against the live endpoint. Test with synthetic or non-sensitive sample files before going live with real patient data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limits","__idx":11},"children":["Rate limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No published per-second or daily rate limits. For high-volume integrations, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@jonda.health"},"children":["support@jonda.health"]}," to discuss capacity planning."]}]},"headings":[{"value":"Best Practices","id":"best-practices","depth":1},{"value":"Callback endpoint reliability","id":"callback-endpoint-reliability","depth":2},{"value":"Always verify callback authenticity","id":"always-verify-callback-authenticity","depth":2},{"value":"Handle both Content-Type values","id":"handle-both-content-type-values","depth":2},{"value":"Choosing an output format","id":"choosing-an-output-format","depth":2},{"value":"Handling result values","id":"handling-result-values","depth":2},{"value":"Use status polling as a safety net","id":"use-status-polling-as-a-safety-net","depth":2},{"value":"File upload","id":"file-upload","depth":2},{"value":"API key security","id":"api-key-security","depth":2},{"value":"Data retention","id":"data-retention","depth":2},{"value":"Environments","id":"environments","depth":2},{"value":"Rate limits","id":"rate-limits","depth":2}],"frontmatter":{"seo":{"title":"Best Practices — Pathology — JondaX API Docs","description":"Best practices for integrating the JondaX Pathology module. Covers callback reliability, output format selection, payload type handling, API key security, status polling, and data retention."}},"lastModified":"2026-09-29T04:36:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/pathology/best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}