# Best Practices

## Callback endpoint reliability

- 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.


## Always verify callback authenticity

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.

## Handle both `Content-Type` values

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

| Payload type | Content-Type |
|  --- | --- |
| Inline (JSON) | `application/json` |
| Inline (FHIR JSON) | `application/fhir+json` |
| File (all formats) | `multipart/form-data` |


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

| Output format | File part Content-Type |
|  --- | --- |
| JSON | `application/json` |
| HL7 | `application/hl7-v2` |
| FHIR JSON | `application/json` |
| FHIR XML | `application/fhir+xml` |
| CSV | `text/csv` |
| Parquet | `application/octet-stream` |


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.

## Choosing an output format

| Format | Best for |
|  --- | --- |
| JSON Inline | Simple integrations — parse `Results[]` directly from the request body |
| JSON File | Same data as inline but delivered as a file attachment alongside metadata |
| HL7 | EHR/LIS systems that already consume HL7 v2.3 messages |
| FHIR JSON | FHIR R4-compatible systems; inline delivery keeps the bundle as the raw body |
| FHIR XML | FHIR R4-compatible systems that require XML serialization |
| CSV | Spreadsheet tools, ETL pipelines, or any tabular consumer |
| Parquet | Data warehouses, analytics pipelines, or high-volume result sets |


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

## Handling result values

`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"`.

## Use status polling as a safety net

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.

## File upload

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


## API key security

- 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.


## Data retention

`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.

## Environments

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.

## Rate limits

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