Developer Guide

Developer documentation for extending and maintaining the system.

Patient Record Import API

Open Clinical History provides a REST-style API for submitting patient history documents directly into the clinical-history processing pipeline.

The API endpoint is:

history_api_import.php

For example:

https://www.openclinicalhistory.org/demo/history_api_import.php

The API can:

The API uses the same clinical processing pipeline and safety rules as the interactive patient-history importer.

API Processing Flow

A typical API import follows this sequence:

External Clinical System
        |
        | POST patient + document
        v
history_api_import.php
        |
        v
Find/Create Patient
        |
        v
Store Source Document
        |
        v
Ingest Queue
        |
        v
queue_worker.php
        |
        v
Clinical Extraction
        |
        v
SNOMED Resolution
        |
        v
Anatomical Mapping
        |
        v
Clinical Audit
        |
        +---------------------------+
        |                           |
        v                           v
Safe event                    Needs review
        |                           |
        v                           v
Committed               Unmatched/Learning Queue
        |
        v
Patient Clinical History

Processing is asynchronous.

A successful import request normally means:

The document has been accepted and queued for processing.

It does not mean extraction has already completed.

The caller should use the returned status URL to monitor progress.

Prerequisites

Before using the API:

  1. Open Clinical History database migrations must be complete.

  2. The API must be enabled in Admin → Configuration.

  3. At least one API token must have been created.

  4. The required LLM configuration must be available.

  5. The SNOMED and image/SNOMED databases should have been built.

  6. If the ingest queue is enabled, queue_worker.php must be running.

Relevant configuration settings include:

api_enabled
api_require_https
api_default_auto_commit
api_max_upload_mb

queue_enabled
queue_max_attempts
queue_job_timeout
queue_lease_seconds

Authentication

Every API request requires an Open Clinical History API token.

Tokens are created under:

Admin → Configuration → API Tokens

The preferred authentication method is an HTTP Bearer token:

Authorization: Bearer och_your_token_here

A fallback header is also supported:

X-API-Token: och_your_token_here

Bearer authentication should be preferred.

Token security

API tokens are secrets.

They should:

Open Clinical History stores only the SHA-256 hash of the token. The full plaintext token is displayed only once when it is created.

API Scopes

Tokens can carry three scopes.

Scope Purpose
import Submit patient history documents
status Read document, processing and queue status
commit Run the clinical audit/commit process

A normal integration using automatic commit generally requires:

import
status
commit

If auto_commit is enabled for an import, the calling token must have the commit scope as well as import.

A token without the required scope receives:

HTTP 403

with:

{
  "ok": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not carry the required scope."
  }
}

HTTPS

By default:

api_require_https = enabled

Requests made without HTTPS are rejected.

The API recognises HTTPS through:

The latter allows Open Clinical History to operate correctly behind an HTTPS reverse proxy.

HTTPS should remain mandatory for environments containing clinical information.

Response Format

Every API response uses JSON.

Successful response:

{
  "ok": true,
  "data": {
  }
}

Error response:

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Description of the error."
  }
}

Applications should check both:

  1. the HTTP status code; and

  2. the ok property.

API Endpoints

The following actions are available.

Method Action Scope Purpose
GET ping Valid token Test authentication and API availability
POST import import Submit a patient history
GET status status Monitor extraction/import progress
GET document status Retrieve the document processing summary
POST commit commit Audit and commit extracted events
GET queue status Inspect the ingest queue
POST queue status + import Retry or cancel queue work

Testing the Connection

Use:

GET history_api_import.php?action=ping

Example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=ping"

A successful response resembles:

{
  "ok": true,
  "data": {
    "build": "2026-08-22.api-v2-app-config-llm",
    "token": {
      "id": 4,
      "label": "Clinical integration",
      "scopes": [
        "import",
        "status",
        "commit"
      ]
    },
    "date_format": "dd/mm/yyyy",
    "queue": {
      "enabled": true,
      "depth": {
        "queued": 0,
        "running": 1,
        "done": 42,
        "failed": 0,
        "cancelled": 0
      }
    },
    "server_time": "2026-08-25T19:45:00+10:00"
  }
}

This provides a useful initial connectivity test because it confirms:

Importing a Patient Record

Use:

POST history_api_import.php?action=import

The preferred request format is:

Content-Type: application/json

Example request:

{
  "record_number": "MRN-1001",
  "display_name": "Example Patient",
  "dob": "1967-04-02",
  "sex": "female",
  "source_name": "hospital-discharge-summary.txt",
  "text": "Patient clinical history goes here...",
  "auto_commit": true,
  "external_ref": "hospital-a:MRN-1001:discharge:84721"
}

Import Fields

record_number

Required

Example:

"record_number": "MRN-1001"

Maximum length:

64 characters

This is the primary external patient identifier used by the patient-import API.

Open Clinical History searches for an existing patient where:

patient_record_number = supplied record_number
source_system = history_import

If found, that patient is reused.

If not found, a new patient is created.

Important

The API is currently a find-or-create patient API, not a demographic-update API.

If the patient already exists, supplying different:

does not update the existing patient record.

The record_number should therefore be stable for the lifetime of the patient within the source integration.

display_name

Optional

Example:

"display_name": "Example Patient"

Used as the patient's human-readable display name when a new patient is created.

It is stored with the patient's attributes.

It is not used as the primary patient-matching key.

dob

Optional

Preferred format:

YYYY-MM-DD

Example:

"dob": "1967-04-02"

ISO dates are recommended for all machine integrations.

The API also accepts the date format configured under:

Admin → Configuration → Date format

For example:

02/04/1967

when the system is configured for dd/mm/yyyy.

Validation

The date:

An invalid value produces:

bad_dob

Machine integrations should always use ISO YYYY-MM-DD to avoid regional date ambiguity.

sex

Optional

Accepted values are:

female
male
intersex
unknown

Values are case-insensitive.

If omitted:

unknown

is used.

An unrecognised value is currently normalised to:

unknown

rather than causing the request to fail.

source_name

Optional

Identifies the source document.

Example:

"source_name": "cardiology-letter-2026-08-25.txt"

Default:

api-upload.txt

A meaningful source name is strongly recommended because it makes individual documents easier to identify in Open Clinical History.

text

Required for JSON imports

Contains the complete unstructured source document.

Example:

"text": "12 March 2018 - Patient admitted with..."

The document can contain raw clinical text.

It does not need to be pre-classified into clinical events or SNOMED concepts.

Open Clinical History performs that processing.

The document must not be empty.

auto_commit

Optional

Boolean:

"auto_commit": true

or:

"auto_commit": false

If omitted, the value comes from:

api_default_auto_commit

in Admin → Configuration.

When true, the API token must have the:

commit

scope.

What auto-commit actually means

Auto-commit does not mean every extracted event is blindly inserted into the patient's clinical history.

After extraction, Open Clinical History performs its normal audit checks.

An event is automatically committed only when it satisfies the safety criteria.

Among other things, a proposal must:

Safe events are committed.

Events that cannot be safely committed are rejected from automatic commit and routed to the unmatched/learning workflow for further resolution.

Conceptually:

Extracted proposal
        |
        v
Clinical audit
        |
        +---- safe -----------------> Commit
        |
        +---- uncertain/unsafe -----> Review/Learning Queue

This allows unattended imports without treating every AI-generated proposal as trusted clinical data.

external_ref

Optional but strongly recommended

Example:

"external_ref": "hospital-a:MRN-1001:discharge:84721"

This provides request-level idempotency.

If the same import request is retried with the same external_ref, Open Clinical History does not create another import.

Instead, it returns the existing document and its current processing state.

The response includes:

"duplicate": true

and returns HTTP:

200 OK

rather than creating a second queue item.

This is particularly important when an integration cannot determine whether an earlier HTTP request reached the server.

Use a stable source-system identifier such as:

<system>:<patient>:<document-id>

For example:

hospital-a:MRN-1001:document-84721

or:

pms:48392:consultation-998312

The maximum stored length is approximately:

190 characters

The current implementation searches external_ref globally rather than per token, so integrations should ensure that external references are globally unique across Open Clinical History.

Optional priority

The JSON import endpoint also accepts:

"priority": 0

This controls ordering within the ingest queue.

Allowed effective values are:

-10 to +10

Higher numbers are processed before lower numbers.

For example:

"priority": 5

will be processed before a queued document with:

"priority": 0

Within the same priority, older queue items are processed first.

For normal integrations, leave this at:

0

unless there is a genuine requirement for priority processing.

Example JSON Import

curl -X POST \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=import" \
  -H "Authorization: Bearer och_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "record_number": "MRN-1001",
    "display_name": "Example Patient",
    "dob": "1967-04-02",
    "sex": "female",
    "source_name": "specialist-letter.txt",
    "text": "Clinical document contents...",
    "auto_commit": true,
    "external_ref": "hospital-a:MRN-1001:letter-84721"
  }'

Successful Import Response

When queue processing is enabled, a successful import normally returns:

HTTP 202 Accepted

with a response similar to:

{
  "ok": true,
  "data": {
    "document_id": 142,
    "patient_id": 27,
    "queue_id": 81,
    "queue_position": 2,
    "state": "queued",
    "auto_commit": true,
    "external_ref": "hospital-a:MRN-1001:letter-84721",
    "status_url": "/demo/history_api_import.php?action=status&doc=142",
    "poll_after": 15
  }
}

document_id

Open Clinical History identifier for the uploaded source document.

Keep this identifier when monitoring the import.

patient_id

Internal Open Clinical History patient identifier.

This may refer to:

queue_id

Identifier of the ingest queue item.

queue_position

Number of queued items currently ahead of this item.

Therefore:

0

means no queued items are ahead of it.

Queue positions can change while workers process other records.

state

Immediately after queue submission:

queued

is normally returned.

status_url

Relative URL that can be used to monitor the document.

Example:

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

Authentication is still required when using this URL.

poll_after

Suggested number of seconds before polling again.

In queue mode the API currently returns:

15

seconds.

Clients should respect this value rather than aggressively polling the server.

Importing a File

The API also supports:

multipart/form-data

Use a file part named:

history

For example:

curl -X POST \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=import" \
  -H "Authorization: Bearer och_your_token_here" \
  -F "record_number=MRN-1001" \
  -F "display_name=Example Patient" \
  -F "dob=1967-04-02" \
  -F "sex=female" \
  -F "auto_commit=true" \
  -F "external_ref=hospital-a:MRN-1001:document-84721" \
  -F "history=@discharge-summary.txt"

When a file is uploaded, its filename becomes the document's source_name.

Maximum Document Size

The maximum accepted document size is controlled by:

api_max_upload_mb

under:

Admin → Configuration

Default:

2 MB

The limit applies to both:

Documents exceeding the limit receive:

HTTP 413 Payload Too Large

with error code:

too_large

Character Encoding

Clinical text is expected to be UTF-8.

If uploaded text is not valid UTF-8, the current importer attempts to convert it from:

ISO-8859-1

to UTF-8 before storing it.

Integrating systems should supply UTF-8 directly wherever possible.

Duplicate Source Documents

Open Clinical History also calculates a SHA-256 hash of the normalised document text.

For a given patient, if identical document content has already been stored, the existing document can be reused rather than storing another physical copy.

However:

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

The document hash protects against identical content. external_ref identifies the source-system transaction/document itself.

Monitoring an Import

Use:

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

Requires:

status

scope.

Example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=status&doc=142"

Import States

The high-level API state may be:

State Meaning
queued Waiting for an ingest worker
extracting Clinical extraction is running
extracted Extraction finished; automatic commit was not requested
committed Audit/commit processing has completed
failed Processing failed after available attempts
cancelled Queue work was manually cancelled

A typical automatic-import sequence is:

queued
   |
   v
extracting
   |
   v
committed

Without auto-commit:

queued
   |
   v
extracting
   |
   v
extracted

The client can then explicitly call the commit endpoint.

Example Status Response

A status response can resemble:

{
  "ok": true,
  "data": {
    "document_id": 142,
    "patient_id": 27,
    "source_name": "specialist-letter.txt",
    "document_state": "committed",
    "status_note": null,
    "char_count": 18492,
    "state": "committed",
    "queue": {
      "id": 81,
      "state": "done",
      "position": 0,
      "attempts": 1,
      "max_attempts": 3,
      "available_at": "2026-08-25 19:40:10",
      "started_at": "2026-08-25 19:40:12",
      "finished_at": "2026-08-25 19:41:44",
      "last_error": null
    },
    "auto_commit": true,
    "external_ref": "hospital-a:MRN-1001:letter-84721",
    "message": null,
    "job": "7a2d4c9e14f0b581",
    "extraction": {
      "state": "done",
      "phase": "complete",
      "chunks_total": 5,
      "chunks_done": 5,
      "events": 19,
      "requests": 7,
      "tokens": 14231,
      "started": 1787643612,
      "updated": 1787643704,
      "errors": []
    },
    "proposals": {
      "proposed": 0,
      "committed": 17,
      "rejected": 2
    },
    "committed": 17,
    "queued": 2,
    "status_url": "/demo/history_api_import.php?action=status&doc=142"
  }
}

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

Understanding the Status Response

document_state

The current status stored against the source document itself.

This is distinct from the high-level API state.

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

char_count

Number of characters in the stored source document.

queue

Contains ingest-queue information when queue mode is enabled.

queue.state

Possible queue-level states are:

queued
running
done
failed
cancelled

attempts

Number of times a worker has claimed the queue item.

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

max_attempts

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

last_error

The most recent queue processing error, if any.

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

queued

Extraction Progress

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

It may contain:

state
phase
chunks_total
chunks_done
events
requests
tokens
started
updated
errors

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

The extraction object may be:

null

before a worker job has been created.

Proposal Counts

The status response contains:

"proposals": {
  "proposed": 0,
  "committed": 17,
  "rejected": 2
}

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

proposed

Events that still await a final decision.

committed

Events accepted into the patient's clinical history.

rejected

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 Value

There are two different queue concepts in the API response.

queue

The object:

"queue": {
  "state": "running"
}

describes the document ingest queue.

queued

The top-level numeric value:

"queued": 2

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

It does 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>

Example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=status&job=7a2d4c9e14f0b581"

Job identifiers are 16 lowercase hexadecimal characters.

For most integrations, monitoring by:

document_id

is simpler.

Document Endpoint

Use:

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

Requires:

status

scope.

Example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=document&doc=142"

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

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:

extracted

To run the audit and commit stage:

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

Requires:

commit

scope.

Example:

curl -X POST \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=commit&doc=142"

A successful response resembles:

{
  "ok": true,
  "data": {
    "document_id": 142,
    "patient_id": 27,
    "state": "committed",
    "committed": 17,
    "queued": 2,
    "errors": []
  }
}

Again:

committed

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

queued

is the number routed to the unmatched/learning workflow.

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

with:

still_extracting

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

Ingest Queue

When:

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

Use:

GET history_api_import.php?action=queue

Requires:

status

scope.

Example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=queue"

The response includes:

By default the most recent:

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

Use:

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

For example:

curl \
  -H "Authorization: Bearer och_your_token_here" \
  "https://www.openclinicalhistory.org/demo/history_api_import.php?action=queue&id=81"

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.

Use:

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

Requires both:

status
import

scopes.

Retry:

Cancel a Queue Item

Use:

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

Requires:

status
import

scopes.

Cancellation is allowed when the queue item is:

queued

or:

failed

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:

failed

Worker Leases

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

The lease is controlled by:

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:

running

Recommended Client Workflow

A robust integration should use the following pattern:

1. Generate stable external_ref
        |
        v
2. POST action=import
        |
        +---- HTTP 202 ----+
        |                  |
        v                  |
   Save document_id        |
   and queue_id            |
        |                  |
        v                  |
3. Wait poll_after         |
        |                  |
        v                  |
4. GET action=status       |
        |                  |
        +---- queued ------+
        |
        +---- extracting --+
        |
        +---- committed ----------> Complete
        |
        +---- extracted ----------> POST commit if required
        |
        +---- failed -------------> Investigate/retry
        |
        +---- cancelled ----------> Stop/re-submit if appropriate

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.

Recommended Polling Behaviour

After submission, use the returned:

"poll_after": 15

value.

A simple client strategy is:

Submit
  |
wait 15 seconds
  |
check status
  |
still processing?
  |
yes -> wait again
  |
no -> process result

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:

{
  "record_number": "MRN-1001",
  "text": "Clinical history...",
  "external_ref": "hospital-a:document-84721",
  "auto_commit": true
}

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

The client may safely resend:

{
  "record_number": "MRN-1001",
  "text": "Clinical history...",
  "external_ref": "hospital-a:document-84721",
  "auto_commit": true
}

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:

patient_record_number
+
source_system = history_import

It does not currently match using:

Therefore:

MRN-1001

must consistently refer to the same patient.

Existing patient

If the patient already exists:

reuse patient

New record number

If it does not exist:

create new patient

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

Patient Asset Set

When a patient is first created by this API:

sex = male

selects the:

male

anatomical asset set.

The current implementation uses the:

female

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:

HTTP Meaning
200 Request completed successfully
202 Import accepted for asynchronous processing
400 Invalid request or field
401 Missing, invalid, expired or revoked token
403 Token does not have the required scope
404 Document, job or queue item does not exist
405 Incorrect HTTP method
409 Current state does not permit the requested operation
413 Document exceeds the configured size limit
422 Document/patient could not be stored or linked
500 Internal application error
503 API, queue or worker unavailable/configuration incomplete

Common API Error Codes

Authentication

missing_token
invalid_token
insufficient_scope

Configuration

not_configured
api_disabled
https_required
queue_disabled

Request format

bad_json
method_not_allowed
unknown_action
missing_target

Document import

missing_text
empty_document
too_large
upload_failed
missing_record_number
bad_record_number
bad_dob
store_failed
link_failed
worker_unavailable

Processing

still_extracting
bad_job
not_found

Queue management

unknown_op
not_applicable

Example Error

An invalid date may return:

HTTP 400

{
  "ok": false,
  "error": {
    "code": "bad_dob",
    "message": "dob must be ISO YYYY-MM-DD or the configured display format (dd/mm/yyyy)."
  }
}

Applications should use the machine-readable:

error.code

for program logic and treat:

error.message

as diagnostic information.

Queue Worker Requirement

When the ingest queue is enabled:

queue_enabled = true

submitting a document does not directly perform extraction.

It creates a queue item.

At least one instance of:

queue_worker.php

must therefore be running.

If no worker is running, submissions can still return:

202 Accepted

but will remain in:

queued

until a worker becomes available.

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

Behaviour Without the Queue

If the 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

but contains a job identifier rather than queue information.

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:

status

scope can currently query API document and queue status generally.

A token with:

commit

scope can request a commit for a supplied document identifier.

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

Therefore:

API tokens should currently be treated as trusted integration credentials for the Open Clinical History installation, rather than as isolated per-patient or per-tenant credentials.

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:

{
  "record_number": "MRN-1001",
  "text": "Clinical history text"
}

All other fields have defaults or are optional.

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

{
  "record_number": "MRN-1001",
  "display_name": "Example Patient",
  "dob": "1967-04-02",
  "sex": "female",
  "source_name": "specialist-letter-84721.txt",
  "text": "Clinical history text...",
  "auto_commit": true,
  "external_ref": "source-system:MRN-1001:84721"
}

Recommended Production Sequence

Create API token
        |
        v
GET ping
        |
        v
POST import
        |
        v
Store document_id
        |
        v
Poll status
        |
        +---- queued/extracting ---> continue polling
        |
        +---- committed -----------> finished
        |
        +---- extracted -----------> commit if required
        |
        +---- failed --------------> investigate/retry

Summary

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

The API deliberately separates:

Submission
    |
    v
Asynchronous extraction
    |
    v
Clinical audit
    |
    v
Safe commit

This means external systems can provide raw, unstructured clinical 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.