Classify Inbox files

This guide extends Send cases to the Inbox. You can skip it for a first test and upload files without a type.

Use semantic_type for machine meaning

Set semantic_type whenever your system knows the file's clinical role. For example, use lower_ios for a lower intraoral scan, bite_scan for an occlusion scan, and prescription for a PDF prescription. This gives Relu an unambiguous type immediately, so downstream processing can start sooner.

Relu stores semantic_type as the manual classification and does not replace it with an automatic guess.

{
  "original_file_name": "upper.stl",
  "extension": ".stl",
  "mime_type": "application/octet-stream",
  "size_bytes": 1843200,
  "semantic_type": "upper_ios",
  "display_name": "Upper jaw"
}

Do not put your own label in semantic_type. An unknown value returns 422. Keep a source-specific label in source_metadata.data instead, or use semantic_type: "other" when you know that the file is supporting material but none of the canonical types fit.

The older type field is an order-slot hint such as upper_jaw. It is not the file's canonical classification. New Inbox integrations should use semantic_type.

Canonical types

Let Relu classify the file

Omit semantic_type if your system does not know the canonical type. If the scanner returns metadata with the file, pass that metadata to Relu in source_metadata. You do not need to translate the scanner's file labels into Relu types first.

Relu can use the scanner metadata together with the file name, extension, and MIME type to determine the file type. If there is not enough evidence, Relu keeps the file for review instead of assigning a type at random.

For a reviewed scanner profile, wrap the file record returned by the scanner in a version 1 envelope. Keep the scanner's original field names and values:

{
  "schema_version": 1,
  "source": "dscore",
  "source_file_id": "digitalImpressions/scan-4382",
  "file_record": {
    "uri": "digitalImpressions/scan-4382",
    "label": "LOWER_JAW"
  },
  "transform": { "kind": "direct" }
}

Use source_metadata for records that describe an individual file. If the scanner also returns case-level prescription information, pass that response in metadata.additional_metadata.<scanner> when you create the Inbox case. Relu can use reviewed scanner profiles to derive prescription information from that data. See Send an Inbox prescription.

The following version 2 envelope shows how to preserve raw metadata from an unsupported scanner or an internal system:

{
  "original_file_name": "scan-4382.mesh",
  "extension": ".mesh",
  "mime_type": "application/octet-stream",
  "size_bytes": 845221,
  "source_metadata": {
    "schema_version": 2,
    "source_system": "private-lms",
    "profile": "private-lms.scan-file.v1",
    "source_file_id": "file-4382",
    "source_revision": {
      "kind": "integer",
      "value": 7
    },
    "data": {
      "scanner_vendor": "Example Scanner",
      "scanner_file_type": "MaxillaryArch",
      "acquisition_mode": "intraoral",
      "internal_tags": ["ready-for-lab", "primary-scan"]
    }
  }
}

Put the file record in data without renaming its fields. source_system and profile are optional identifiers. Relu sanitizes and stores unknown evidence, but only reviewed scanner profiles affect automatic classification or prescription extraction. At present, those profiles cover 3Shape, 3DISC, DScore, iTero, Medit, Panda, and Shining 3D.

Metadata safety rules

Keep source metadata technical. Put the patient's name, doctor, dates, and case notes in the case-level metadata object.

Relu removes unsafe or private fields from source_metadata, including:

• API keys, tokens, passwords, cookies, authorization headers, and secrets.
• Signed upload or download URLs, request bodies, binary data, and base64 file content.
• Patient, doctor, contact, demographic, insurance, and national identity data.

Do not use source metadata as a file transport. Upload the bytes through the signed URL returned by the registration endpoint.

The envelope is bounded by the API. Deeply nested data, oversized payloads, unsafe archive paths, and malformed revisions return 422. Test a metadata object without registering a file by calling POST /inbox-cases/source-metadata/preflight.

Classification order

Relu applies these rules in order:

1. A valid explicit semantic_type wins.
2. Reviewed scanner evidence may provide a classification.
3. Relu may use source-independent facts such as the file name and extension.
4. If the evidence is not clear, the file remains unclassified for review.

Case-level source and file-level source_metadata are independent. One case may contain files from several scanners or internal systems.