Best Practices

Quick tips:

• Make sure your callback URL is reachable and responding before uploading files
• If results don't arrive, check the Transformed Files page in the portal — your output may be there for download
• Store your uploadId (shown after each upload) — support will ask for it if something goes wrong
• When in doubt, contact support@jonda.health with your uploadId and a description of the issue

• Ensure your endpoint is highly available and publicly reachable before configuring it in the Integration page.
• Respond with a 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.
• JondaX retries up to 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.
• Log all incoming callback requests including headers and body for troubleshooting.

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.

For FHIR JSON Inline callbacks, the metadata is delivered as X-JondaX-* request headers rather than in the body. Verify your chosen auth header is present alongside these headers.

Your endpoint must accept both content types depending on the configured payload type:

The file part within each multipart callback carries its own content-type:

For File-type callbacks, always read the metadata part first — it carries customerId, uploadId, fileName, transactionId, outputFormat, and totalTests without having to parse the result file.

CSV and Parquet use identical columns in the same order — switching between them requires no schema changes on your end.

Results[].Result is always a string and can take several forms — handle all of them:

• Numeric: "17.00"
• Qualitative: "NEGATIVE", "POSITIVE", "NORMAL"
• Flagged numeric: "0.52 H" (value plus a flag character)
• With comparator: "<0.1"
• Empty string: "" — result not detected or not available

Similarly, Low-Ref-Range and High-Ref-Range may be empty, numeric strings, or include a comparator prefix like "<0.3".

Always store the uploadId returned from each upload. If your callback endpoint was unreachable or you suspect a delivery issue, poll the status endpoint to check:

GET https://app.jondax.eu/api/v1/status/:uploadId
Authorization: Bearer <JONDAX_API_KEY>

Check callbackDelivery.status — if it is exhausted, contact support with the uploadId to retrieve the stored result before the 30-day retention window closes.

• Validate file size (max 10 MB) and format on the client side before uploading to avoid unnecessary round trips.
• Supported formats: PDF, HL7, XML, JSON, CSV, Parquet, and Images (PNG, JPEG, HEIC, HEIF, GIF, AVIF, WEBP, BMP, TIFF).
• Use descriptive filenames with ASCII characters. Avoid special symbols or excessively long names.

• Store the API key in environment variables or a secrets manager — never in client-side code or source control.
• Rotate the key immediately from the Integration page if it is exposed.
• Use the same API key consistently for uploads and status polling — the status endpoint enforces ownership and will return 403 if the key does not match the one used to create the upload.

uploadId values and associated results are retained for 30 days from the upload date. After expiry the record returns 404 and the data is permanently purged. Retrieve or store any results you need before the window closes.

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.

No published per-second or daily rate limits. For high-volume integrations, contact support@jonda.health to discuss capacity planning.