JSON input / BiomDIRECT

Use BiomDIRECT for biometry data from your integration, script, EHR, or manual entry. BiomDIRECT labels the source of the data. BiomJSON validates and normalizes the JSON without calling Gemini.

You do not need to create a complete StandardAPIResponse or supply metadata. Submit the required report objects and any available measurements. BiomAPI validates them and builds the standard response. It adds metadata and sets omitted optional fields to null.

Minimal input

This complete JSON object passes validation without metadata or measurements:

{
  "data": {
    "biometer": {
      "device_name": "IOLMaster700",
      "manufacturer": "Zeiss"
    },
    "patient": {},
    "right_eye": {},
    "left_eye": {}
  }
}

Use the actual device and manufacturer values when known. "Other" is available for an unrecognized device or manufacturer.

The input must contain:

• A top-level data object.
• biometer, patient, right_eye, and left_eye objects inside data.
• device_name and manufacturer inside biometer.

Patient and eye objects can be empty ({}). Do not omit them or replace them with null.

Patient fields, exam_date, and individual measurements may be omitted or set to null. Add measurements inside the appropriate eye object, using the exact field names, enum values, and units in the field reference. See the complete synthetic report for an example with measurements.

Supply CCT in whole micrometers and all K, PK, and TK axes in whole degrees. Fractional values for these fields fail validation; BiomAPI does not round them.

Input with notes and source attribution

Keep the core report inside data. Add optional extra_data and metadata alongside it:

{
  "data": {
    "biometer": { "device_name": "Argos", "manufacturer": "Alcon" },
    "patient": {},
    "right_eye": { "AL": 23.45 },
    "left_eye": {}
  },
  "extra_data": { "notes": "Synthetic example; not a patient report." },
  "metadata": {
    "schema_version": "1.0.0",
    "extraction": {
      "method": "BiomDIRECT",
      "source_app": "Example EHR",
      "source_version": "1.0.0"
    }
  }
}

Only data is required at the top level. Its contents must follow the requirements above. Put notes, posterior keratometry, and total keratometry in top-level extra_data.

If either eye has a non-null TK field, extra_data.posterior_keratometry.pk_device_name must be IOLMaster700. This requirement applies independently of the main biometer. The eye fields are under extra_data.posterior_keratometry.right_eye and .left_eye. See the extra-data reference.

Use optional source_app and source_version fields under metadata.extraction to declare your application’s name and version. These fields record provenance; they do not authenticate your application or establish trust.

Omit unused metadata blocks. If you supply metadata or metadata.extraction, each must be an object, not null. New BiomDIRECT input does not need a schema version or extraction method.

What BiomAPI adds

You supply	BiomAPI adds or returns
Required report objects and available values	Validated data, with omitted optional fields populated as null
Optional extra_data	Validated notes, posterior keratometry, and total keratometry, or extra_data: null when absent
No extraction metadata for newly constructed JSON	metadata.extraction.method: "BiomDIRECT"
Optional metadata.extraction.source_app and source_version	The supplied source fields, or null when omitted
Optional metadata.extraction.timestamp	The supplied parseable ISO timestamp; current UTC time when missing or invalid
Optional metadata.schema_version	The current response metadata.schema_version; extraction.input_schema_version records the input version, defaulting to the current schema when omitted
No response request ID or app version needed	A request correlation ID and the current server metadata.app_version
Optional biompin=true request form field	A newly created share when available; otherwise biompin: null

The current schema is 1.1.0, adding optional TK fields and accepting PK magnitudes from 2–10 D. Existing 1.0.0 documents remain accepted.

If declared, the input schema version must have the supported major version. Minor and patch differences are accepted. The response metadata reference describes the returned fields.

Reports without data return HTTP 422. Keep report fields inside data. Keep extra_data, metadata, and biompin outside data. Mixing report fields at the root or nesting these other objects inside data also returns HTTP 422.

BiomAPI fills optional fields and metadata. It does not create missing required report objects, infer measurements, or repair inconsistent keratometry.

Validation fails for missing required fields, invalid enums, out-of-range measurements, or inconsistent K/PK/TK pairs. Follow the anterior keratometry rules and the shared PK and TK field and validation reference.

Validation also applies documented normalization, including patient names to initials and signed posterior powers to positive magnitudes. A missing measurement remains null; it does not mean zero, normal, or confirmed absent. Schema validation cannot establish clinical correctness.

Submit the JSON

Save either complete input example as a UTF-8 file named report.json, then upload it using multipart file:

curl --fail-with-body https://biomapi.com/api/v1/biom/process \
  -F "file=@report.json" \
  -o result.json

The .json extension is required for JSON routing. The endpoint expects a file upload, not an application/json request body. Open result.json to read the completed response.

Add -F "biompin=true" to request a new BiomPIN share. Sharing is off by default; check the returned biompin because processing may succeed even if a share cannot be created. See the REST API for authentication, options, and errors.

Re-upload a saved response

A saved StandardAPIResponse is also accepted as the uploaded JSON file. BiomJSON revalidates data and any extra_data against the current rules, then reconstructs supported extraction provenance.

BiomJSON preserves declared BiomAI provenance, including the model, BYOK flag, and parseable timestamp. For BiomDIRECT, it preserves direct-entry source fields.

It records the input version as metadata.extraction.input_schema_version. It sets the response schema/app versions and request ID for the new processing request. The saved response is therefore updated, rather than returned unchanged.

Provenance preservation does not detect edits or prove that a file is unmodified. If you edit extracted values outside the web app, set metadata.extraction.method to "BiomDIRECT" and remove obsolete BiomAI-specific fields. Web-app edits make that provenance change automatically.

Uploaded biompin information is not reused. Request biompin=true as a form field to create a new share; without it, the response has biompin: null.