API for the Exchange of Medicinal Product Information (APIX)
0.1.0 - ci-build International flag

API for the Exchange of Medicinal Product Information (APIX), published by HL7 International / Biomedical Research and Regulation. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/APIX---API-Exchange-for-Medicinal-Products/ and changes regularly. See the Directory of published versions

Workflow Deep-Dive

Page standards status: Informative

Workflow Deep-Dive

Detailed technical walkthrough of a "shelf-life update" scenario, illustrating every FHIR resource exchange between a Company and a Regulator.

💡 Looking for a business-friendly overview? Start with the Workflow Overview page first.
⚠️ Notification Mechanism

The Regulator does not directly "send" messages. Instead, it updates Task.status on the server. The Company receives notifications via its Subscription whenever a change occurs.

0 Registration & Connection
Step 0.1 — Company Registers with Regulator

One-time registration with the Regulator's API portal. The Regulator registers the Company as an Organization and provides API credentials. The Company also registers an Endpoint for subscription notifications.

Step 0.2 — Company Connects to API

The Company authenticates via OAuth2, confirming authorization to post resources for their medicinal products.

1 Submission & Validation
Step 1.0 — Company Prepares Submission

Granular "Index Pattern" instead of monolithic ZIP — high performance and scalability even for massive datasets.

Step 1.1 — Upload Binaries & Bundles
Content Type FHIR Resource
PDF DocumentsBinary
Structured Labeling (JSON)Document Bundle
CMC DataTransaction Bundle
Step 1.2 — Create DocumentReferences

Each upload gets a DocumentReference — a "Library Card" with metadata and a pointer to the uploaded resource.

Step 1.3 — Create & Post the Task

The Task is the "Orchestrator" — it holds procedure metadata and references every DocumentReference in Task.input.

📎 JSON · HTML View
Step 2.0 — Regulator Validates
✅ Passes

Status → Accepted. Receipt & results attached.

📎 JSON · HTML
❌ Fails

Missing docs requested → Company re-submits → Re-validation.

2 Review Cycles

Multiple reviews happen in parallel.

Track A — Compliance Check

Regulator checks compliance of the scientific data.

Track B — Financial Review
  1. 5.B.1 — Regulator determines fee is due
  2. 5.B.3 — Company posts proof of payment (Binary → DocumentReference → added as Task output)
  3. 5.B.4 — Regulator verifies proof → Payment Task Completed
📎 JSON · HTML View
Step 5.3 — Issue Resolution Loop
5.3.1 — Regulator Posts Questionnaire

POST Questionnaire → DocumentReference → Question Task (input: DocRef)

📎 JSON · HTML
5.3.2 — Company Posts Response

POST QuestionnaireResponse → DocumentReference → added as Task output

📎 JSON · HTML
5.3.3 — Regulator Reviews Response

If satisfactory → Question Task Completed → review continues.

3 Final Decision
Step 6.0 — Final Decision

Regulator updates Task.status to completed and attaches decision documents to Task.output.

📎 JSON · HTML View

Workflow Diagram

sequenceDiagram
    participant C as Company
    participant R as Regulator
    
    %% Phase 0: Registration
    Note over C,R: Phase 0: Registration & Connection
    C->>R: 0.1 Register with Regulator Portal
    R-->>C: Client Credentials & Org ID
    C->>R: 0.2 OAuth2 Authentication
    
    %% Phase 1: Submission
    Note over C,R: Phase 1: Submission & Validation
    par Upload Binaries/Bundles
        C->>R: 1.1 POST PDFs (Binary)
        C->>R: 1.1 POST Labels (Document Bundles)
        C->>R: 1.1 POST CMC (Transaction Bundles)
    end
    C->>R: 1.2 POST DocumentReferences (IDs/Links)
    C->>R: 1.3 POST Task (Orchestrator Index)
    
    activate R
    R->>R: 2.0 Validate Application
    
    alt Validation Passes
        R-->>C: 3.1 Ack Receipt & Validation Results
    else Validation Fails
        R->>C: 4.1 Request Missing Documents
        C->>R: 4.2.1 Submit Missing Documents
        R->>R: 4.2.2 Re-validate
    end
    
    %% Phase 2: Review
    Note over C,R: Phase 2: Review Cycles
    
    par Parallel Checks
        rect rgb(240, 248, 255)
            Note right of R: Technical Review
            R->>R: 5.2.1 Check Compliance
        end
        
        rect rgb(255, 250, 240)
            Note right of R: Financial Review
            R->>R: Review Financials
            Note over R: 5.B.2 Invoice Sequence
            R->>R: POST Invoice (Binary/Resource)
            R->>R: POST DocumentReference
            R->>C: POST Payment Task (Input: DocRef)
            activate C
            Note over C: 5.B.3 Payment Sequence
            C->>C: POST Proof of Payment (Binary)
            C->>C: POST DocumentReference
            C-->>R: Update Task (Add Output DocRef)
            deactivate C
            R->>R: 5.B.4 Verify Proof & Set Task: completed
        end
    end
    
    loop Issue Resolution
        alt Issue Found
            Note over R: 5.3.1 Question Sequence
            R->>R: POST Questionnaire
            R->>R: POST DocumentReference
            R->>C: POST Question Task (Input: DocRef)
            activate C
            Note over C: 5.3.2 Response Sequence
            C->>C: POST QuestionnaireResponse
            C->>C: POST DocumentReference
            C-->>R: Update Task (Add Output DocRef)
            deactivate C
            R->>R: 5.3.3 Review & Set Task: completed
        else No Issues
            R->>R: Proceed to Decision
        end
    end
    
    %% Phase 3: Decision
    Note over C,R: Phase 3: Final Decision
    
    alt Approved
        R-->>C: 6.1 Notify Approval (Decision Letter)
    else Rejected
        R-->>C: 7.1 Notify Rejection
    end
    deactivate R