Patient Record Import API

External Clinical System

{
  

{
  

{
  

Use:

Example:

curl \

{
  

Use:

{
  

record_number

Example:

patient_record_number = supplied record_number

Important

display_name

Optional

dob

Optional

Example:

Validation

bad_dob

sex

Optional

female

male

intersex

unknown

unknown

unknown

source_name

Optional

Example:

Default:

text

Example:

auto_commit

Optional

or:

api_default_auto_commit

commit

scope.

Conceptually:

external_ref

Example:

::

or:

curl -X POST \

{
  

document_id

patient_id

patient_uuid

Example:

5ab5c79f-a20d-11f1-bdaf-c6baf601d317

patient_url

Example:

/patient.php?p=5ab5c79f-a20d-11f1-bdaf-c6baf601d317

queue_id

queue_position

Therefore:

0

state

queued

status_url

Example:

/demo/history_api_import.php?action=status&doc=142

poll_after

15

seconds.

curl -X POST \

api_max_upload_mb

under:

Default:

too_large

However:

> `external_ref`

external_ref should still be used as the integration's primary idempotency mechanism.

Use:

Requires:

status

scope.

Example:

curl \

A typical automatic-import sequence is:

Without auto-commit:

The client can then explicitly call the `commit`commit endpoint.

Example Status Response

A completed status response can resemble:

The exact values depend on the document and current pipeline stage.

The `patient_uuid`patient_uuid remains the same throughout the lifecycle of the import. A client that did not persist the UUID from the initial import response can recover it from `status`status or `document`document.

Understanding the Status Response

Stable public Open Clinical History identifier for the patient associated with this document.

This value can be persisted by the source system and used to correlate future Open Clinical History links or references to the same patient.

Relative viewer URL constructed from `patient_uuid`patient_uuid.

The current status stored against the source document itself.

This is distinct from the high-level API `state`state.

For normal integrations, `state`state should generally be used to decide what action to take next.

Number of characters in the stored source document.

Contains ingest-queue information when queue mode is enabled.

Possible queue-level states are:

Number of times a worker has claimed the queue item.

A worker claim counts as an attempt even if that worker subsequently disappears.

Maximum number of processing attempts permitted before the item is permanently parked as failed.

The most recent queue processing error, if any.

A job that fails and is automatically retried may therefore have a `last_error`last_error while returning to:

Extraction Progress

The `extraction`extraction object provides lower-level information about the extraction worker.

It may contain:

This can be used to provide richer progress information to an integrating application.

The `extraction`extraction object may be `null`

before a worker job has been created.

Proposal Counts

The status response contains:

These are the extracted clinical event proposals associated with the document.

Events that still await a final decision.

Events accepted into the patient's clinical history.

Events not automatically committed.

Rejected does not necessarily mean that the extracted clinical statement was incorrect.

It may mean that Open Clinical History could not safely establish:

Such events can be routed through the unmatched/learning process.

A Note About the Top-Level `queued`queued Value

There are two different queue concepts in the API response.

The object:

describes the **document ingest queue**queue.

The top-level numeric value:

"queued": 2`

after the audit stage means that two extracted clinical events were routed to the **unmatched/learning workflow**workflow rather than automatically committed.

It does **not**not mean there are two documents ahead of this document in the ingest queue.

Status by Job Identifier

Status can also be requested using the extraction job identifier:

GET history_api_import.php?action=status&job=<job>`

curl \

Job identifiers are 16 lowercase hexadecimal characters.

For most integrations, monitoring by `document_id`document_id is simpler.

Status responses resolved from a job identifier also include the associated `patient_uuid`patient_uuid and `patient_url`patient_url once the document is identified.

Document Endpoint

GET history_api_import.php?action=document&doc=<document_id>`

curl \

The current implementation returns the same assembled document-processing view used by document-based status requests.

That view includes `patient_id`patient_id, `patient_uuid`patient_uuid and `patient_url`patient_url, so the Open Clinical History patient reference can be recovered from a known `document_id`document_id.

This endpoint provides a semantic way for an integration to request the current summary for a known document.

Manual Commit

If the document was imported with:

"auto_commit": false

the normal completed state is:

To run the audit and commit stage:

POST history_api_import.php?action=commit&doc=<document_id>

Requires the:

curl -X POST \

A successful response resembles:

committed is the number of clinical events accepted into the clinical history.

queued is the number routed to the unmatched/learning workflow.

The returned `patient_uuid`patient_uuid is the same stable public patient identifier supplied during the original import.

Commit While Extraction Is Running

The API will not allow a document to be committed while extraction is still active.

It returns:

HTTP 409 Conflict`

The response includes a `status_url`status_url that should be polled until extraction has finished.

Ingest Queue

queue_enabled = true`

API imports are placed into the controlled ingest queue.

This prevents a burst of API submissions from launching an unlimited number of LLM extraction processes.

The queue worker processes them in a controlled sequence.

Inspecting the Queue

GET history_api_import.php?action=queue`

curl \

The response includes:

By default the most recent `25`25 items are returned.

A custom limit can be supplied:

?action=queue&limit=50`

The API permits between:

1 and 100`

items through this endpoint.

Inspecting One Queue Item

GET history_api_import.php?action=queue&id=<queue_id>`

For example:

curl \

The response includes the queue item and its current position.

Retry a Failed Queue Item

A failed or cancelled item can be reset and submitted again.

POST history_api_import.php?action=queue&id=<queue_id>&op=retry`

Requires both:

Cancel a Queue Item

POST history_api_import.php?action=queue&id=<queue_id>&op=cancel`

Cancellation is allowed when the queue item is:

A currently running worker is not cancelled by this endpoint.

Automatic Queue Retries

If processing fails, the queue automatically retries until `queue_max_attempts`

has been reached.

Retry delay uses increasing quadratic backoff.

Conceptually, with successive failed attempts:

attempt 1 -> wait 60 seconds`

attempt 2 -> wait 240 seconds`

attempt 3 -> wait 540 seconds`

The delay is capped at one hour.

Once all allowed attempts have been exhausted, the item is marked:

Worker Leases

When a worker claims a queue item, it receives a temporary lease.

The lease is controlled by `queue_lease_seconds`queue_lease_seconds.

Workers extend their lease while long-running extraction is taking place.

If a worker crashes and its lease expires, the item can be returned to the queue rather than remaining permanently stuck in:

Recommended Client Workflow

A robust integration should use the following pattern:

1. Generate stable external_ref

The critical distinction is:

Do not continuously resubmit the original document while waiting.

Poll the status endpoint instead.

If network uncertainty makes a resubmission necessary, send the **same `external_ref`**external_ref. If the original request was already accepted, the duplicate response returns the existing document state and `patient_uuid`patient_uuid.

Recommended Polling Behaviour

After submission, use the returned:

"poll_after": 15`

A simple client strategy is:

There is no need to poll every second.

Clinical extraction may involve several model requests and can take some time for large documents.

Idempotent Retry Example

Initial request:

Suppose the client's connection fails before it receives the response.

The client may safely resend:

If the original submission was already accepted, the API returns the existing request with:

"duplicate": true`

rather than intentionally creating another import.

Patient Matching Behaviour

Patient matching deserves particular attention when designing an integration.

Open Clinical History currently matches imported patients using:

source_system = history_import`

It does **not**not currently match using:

Therefore:

must consistently refer to the same patient.

Existing patient

If the patient already exists, the API reuses that patient.

New record number

If it does not exist, the API creates a new patient.

Consequently, changing a patient's external record number can create another Open Clinical History patient rather than updating the existing one.

Relationship between `record_number`record_number and `patient_uuid`

These identifiers serve different purposes:

The source system should also retain the returned `patient_uuid`patient_uuid so it has a durable Open Clinical History reference for that patient.

The current API does not require or accept `patient_uuid`patient_uuid as the patient matching key on import.

Patient Asset Set

When a patient is first created by this API, `sex = male`male selects the `male`male anatomical asset set.

The current implementation uses the:

asset set for the other sex values.

This affects the anatomical visual layers used when displaying the patient's history.

Date Handling Recommendation

Although Open Clinical History can accept the configured display format, integrations should always send:

YYYY-MM-DD`

For example:

"dob": "1971-09-05"`

rather than:

"dob": "05/09/1971"`

This makes the payload independent of the user-interface date configuration and avoids ambiguity between Australian and US date formats.

HTTP Status Codes

Common HTTP responses include:

Common API Error Codes

missing_token

Request format

Document import

Queue management

Example Error

An invalid date may return:

HTTP 400`

Applications should use the machine-readable `error.code`code for program logic and treat `error.message`message as diagnostic information.

Queue Worker Requirement

When the ingest queue is enabled:

queue_enabled = true`

submitting a document does **not**not directly perform extraction.

It creates a queue item.

At least one instance of:

must therefore be running.

If no worker is running, submissions can still return `202 Accepted`Accepted but will remain in:

until a worker becomes available.

Queue health should therefore be monitored as part of production operations.

Behaviour Without the Queue

If the `ingest_queue`ingest_queue table is unavailable or:

queue_enabled = false`

the API falls back to its earlier behaviour and spawns an extraction worker for each import.

The response still returns `202 Accepted`Accepted but contains a job identifier rather than queue information.

The response still includes `patient_id`patient_id, `patient_uuid`patient_uuid and `patient_url`patient_url, so the public patient reference is available immediately in this mode as well.

The suggested poll interval becomes:

5 seconds`

This mode is unbounded and is less appropriate for burst or high-volume integrations.

The controlled ingest queue is recommended.

API Security Model

API permissions are capability based.

A token with:

scope can currently query API document and queue status generally.

A token with:

scope can request a commit for a supplied document identifier.

The current API does not restrict documents to the token that originally submitted them.

Use least-privilege scopes and issue separate tokens for different integrations where appropriate.

Suggested Integration Requirements

A production integration should:

Minimum JSON Request

The smallest valid JSON import is:

All other fields have defaults or are optional.

For a real integration, however, the recommended payload is:

Recommended Production Sequence

Create API token

The Open Clinical History patient reference is available before asynchronous clinical processing finishes. There is therefore no need for a source system to wait until `committed`committed before recording the relationship between its own patient and the Open Clinical History patient.

history_api_import.php`php provides the machine-to-machine entry point into the Open Clinical History patient-processing pipeline.

The API deliberately separates:

Patient find/create

This means external systems can provide **raw, unstructured clinical records**records while Open Clinical History performs the extraction, SNOMED classification, anatomical mapping and clinical-safety checks required to turn those records into a longitudinal patient history.

The external system does not need to pre-classify the clinical content before submission.

It also does not need to wait for processing to finish before receiving the Open Clinical History patient identifier. The initial successful import response provides:

For integrations, `patient_uuid`patient_uuid should be stored as the durable Open Clinical History patient reference, while `document_id`document_id should be stored for tracking the lifecycle of each imported document.