API Endpoints

The NPCA EMR Clinical Data Submission API provides endpoints to manage patient visits, authentication, beneficiary search, and processing status. All endpoints require proper authentication and specific headers.

Public Endpoints

These endpoints are publicly accessible and do not require authentication.

1. Get Standard Data

Retrieve various standard data types used throughout the system without authentication.

Field	Value
URL	`GET /v1/external/common/standard-data`
Authentication	None Required
Query Parameters	`type` (required), `per_page` (optional), `query` (optional)

Available Data Types:

marital_statuses - Marital status options
admission_types - Hospital admission types
visit_types - Types of medical visits (OPD, IPD)
discharge_types - Patient discharge types
visit_outcomes - Visit outcome classifications
diagnosis_types - Types of diagnoses (Primary, Secondary, etc.)
payment_types - Payment method options
card_types - Insurance/benefit card types
nationalities - Nationality options
diagnoses - Medical diagnosis codes and descriptions
health_facilities - Healthcare facility information
medications - Available medications and drugs

Query Parameters:

type (required): The type of standard data to retrieve
per_page (optional): Number of records per page (default: 100)
query (optional): Search term to filter results

Example Request:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/common/standard-data?type=diagnoses&per_page=50&query=fever" \
  -H "Accept: application/json"

Example Response:

json

{
  "success": true,
  "http_code": 200,
  "message": "Data retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "code": "R50",
        "name": "Fever, unspecified",
        "description": "Elevated body temperature of unknown origin"
      },
      {
        "code": "A01.0",
        "name": "Typhoid fever",
        "description": "Infection caused by Salmonella typhi"
      }
    ],
    "per_page": 50,
    "total": 125,
    "last_page": 3
  }
}

Data Endpoints

All data endpoints require authentication and specific headers.

Required Headers for Data Endpoints

http

Authorization: Bearer {access_token}
Accept: application/json
Content-Type: application/json
X-System-Code: {system_code}
X-Health-Facility-Code: {facility_code}

2. Search Beneficiary

Search for beneficiary information using card number.

Field	Value
URL	`GET /api/v1/external/beneficiary/search`
Authentication	Bearer Token Required
Query Parameters	`card_number` (required)

Example Request:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/beneficiary/search?card_number=160498163" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020"

Response Fields:

spid: String - System Patient ID
patient_code: String - Unique patient identifier
surname: String - Patient's surname
name: String - Patient's given name
sex: String - Patient's gender (M/F)
birthdate: String (YYYY-MM-DD) - Date of birth
phone_number: String - Contact phone number
nationality: String - Patient's nationality
relationship_to_head: String - Relationship to household head
dead: Boolean - Death status
death_date: DateTime - Date of death (if applicable)
created_at: DateTime - Record creation timestamp
updated_at: DateTime - Last update timestamp
address: Object - Address information
benefit_cards: Array - Benefit card information
identifications: Array - Identification documents
occupation: String - Patient's occupation
disabilities: Array - List of disabilities

3. Submit Visit Data

Submit comprehensive patient visit data including encounters, diagnoses, and treatments.

Field	Value
URL	`POST /api/v1/external/visits`
Authentication	Bearer Token Required
Content-Type	`application/json`

Example Request:

bash

curl -X POST https://demo-authena.pmrs2.org/api/v1/external/visits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020" \
  -d @visit_data.json

4. Get Processing Status

Retrieve the processing status of submitted visits with pagination support.

Field	Value
URL	`GET /api/v1/external/visits/processed`
Authentication	Bearer Token Required

Query Parameters:

per_page: Number of records per page (default: 10)
discharged_at_from: Filter by discharge date from (YYYY-MM-DD)
discharged_at_to: Filter by discharge date to (YYYY-MM-DD)
admitted_at_from: Filter by admission date from (YYYY-MM-DD)
admitted_at_to: Filter by admission date to (YYYY-MM-DD)
processing_status: Filter by processing status
sort_by: Field to sort by
sort_direction: Sort direction (asc/desc)

Example Request:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/visits/processed?per_page=4" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020"

Request Body Structure

The visit submission endpoint accepts a comprehensive JSON structure containing all patient visit data. Below is the complete structure with all available components:

json

{
  "visits": [
    {
      "health_facility_code": "HEFA-0000752S",
      "patient_code": "25014827",
      "code": "V420650",
      "admission_type": "Walk-in",
      "discharge_type": "Authorized",
      "visit_outcome": "Improved",
      "visit_type": "IPD",
      "admitted_at": "2025-03-17T09:30:00.000+07:00",
      "discharged_at": "2025-03-18T10:45:00.000+07:00",
      "followup_at": null,
      "created_at": "2025-03-17T09:30:00.000+07:00",
      "updated_at": "2025-03-18T10:45:00.000+07:00",
      "patient": {
        "code": "25014827",
        "surname": "Doe",
        "name": "John",
        "sex": "F",
        "birthdate": "1992-06-02",
        "phone": "010448687",
        "nationality": "",
        "disabilities": "",
        "occupation": "At home",
        "marital_status": "Married",
        "photos": "",
        "address": {
          "province": {
            "code": "7",
            "name": "Some Province"
          },
          "district": { 
            "code": "708", 
            "name": "Some district" 
          },
          "commune": {
            "code": "70802",
            "name": "Some Commune"
          },
          "village": {
            "code": "7080201",
            "name": "Some Village"
          },
          "house_number": "",
          "street_number": "",
          "location": ""
        },
        "identifications": [
          {
            "patient_code": "25014827",
            "card_code": "110377818(01)",
            "card_type": "National ID"
          }
        ],
        "death_at": null,
        "spid": "6402-60E0DB-C780B6",
        "created_at": "0001-01-01T00:00:00.000+07:00",
        "updated_at": null
      },
      "triages": [
        {
          "patient_code": "25014827",
          "visit_code": " V420650",
          "code": "TR250317",
          "chief_complaint": "Periodic fever with chills for 3 days",
          "height": 170,
          "weight": 65,
          "recorded_at": "2025-03-17T09:32:00.000+07:00",
          "recorded_by": "Khun Srey Mom",
          "title": "Doctor"
        }
      ],
      "vital_signs": [
        {
          "encounter_code": "TR250317",
          "recorded_at": "2025-03-17T09:40:00.000+07:00",
          "recorded_by": "Khun Srey Mom",
          "title": "Doctor",
          "observations": [
            {
              "name": "Systolic Blood Pressure",
              "value": 135
            },
            {
              "name": "Diastolic Blood Pressure",
              "value": 85
            },
            {
              "name": "Heart Rate",
              "value": 92
            },
            {
              "name": "Respiratory Rate",
              "value": 18
            },
            {
              "name": "Temperature",
              "value": 38.7
            },
            {
              "name": "Blood Oxygen",
              "value": 97
            },
            {
              "name": "Random Blood Glucose",
              "value": 110
            }
          ]
        }
      ],
      "medical_histories": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": " Immunization History",
          "value": ["BCG", "OPV", "DTP", "Measles", "COVID-19"]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Allergies",
          "value": ["Prahok", "Shrimp paste", "Penicillin"]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Past Surgical History",
          "value": ["Appendectomy Surgery"]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Past Medical History",
          "value": [
            "Dengue fever (2020)",
            "Typhoid (2018)",
            "Cesarean section at Calmette Hospital (2019)"
          ]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Family History",
          "value": [
            "Mother with diabetes",
            "Father with hypertension and stroke at age 60"
          ]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Current Illness History",
          "value": [
            "Patient reports high fever with chills occurring every 48 hours, accompanied by headache and joint pain. Symptoms started 3 days ago after returning from a trip to Mondulkiri province. No prior history of malaria. No medication taken yet."
          ]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Current Medication",
          "value": ["Metformin 500mg", "Amlodipine 5mg"]
        }
      ],
      "physical_examinations": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417001",
          "name": "General Appearance",
          "value": "Ill-appearing with intermittent shivering",
          "value_type": "text",
          "value_unit": null
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Skin",
          "value": "Warm, jaundiced, no rash",
          "value_type": "text",
          "value_unit": null
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "name": "Digestive System",
          "value": [
            {
              "inspection": "Flat, no visible masses"
            },
            {
              "palpation": "Soft, mild RUQ tenderness, spleen palpable 1cm below costal margin"
            },
            {
              "percussion": "No shifting dullness"
            },
            {
              "auscultation": "Normal bowel sounds"
            }
          ],
          "value_type": "complex",
          "value_unit": null
        }
      ],
      "outpatients": [
        {
          "visit_code": "V420650",
          "code": "E417001",
          "name": "Outpatient Department",
          "symptoms": ["Swelling of the abdomen", "Red skin"], //optional
          "service_type": "General Consultation",
          "started_at": "2025-03-17T09:35:00.000+07:00",
          "ended_at": "2025-03-17T10:15:00.000+07:00",
          "encountered_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "created_at": "2025-03-17T09:35:00.000+07:00",
          "updated_at": "2025-03-17T10:15:00.000+07:00"
        }
      ],
      "inpatients": [
        {
          "visit_code": "V420650",
          "code": "E417002",
          "name": "Inpatient Department",
          "symptoms": ["Swelling of the abdomen", "Red skin"], //optional
          "service_type": "Internal Medicine",
          "started_at":  "2025-03-17T10:15:00.000+07:00",
          "ended_at": "2025-03-18T10:45:00.000+07:00",
          "encountered_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "created_at": "2025-03-17T09:35:00.000+07:00",
          "updated_at": "2025-03-17T10:15:00.000+07:00"
        }
      ],
      "emergencies": [
        {
          "visit_code": "V420650",
          "code": "E417003",
          "name": "Emergency Department",
          "symptoms": ["Swelling of the abdomen", "Red skin"], //optional
          "service_type": "Emergency",
          "started_at": "2025-03-17T15:30:00.000+07:00",
          "ended_at": "2025-03-17T17:45:00.000+07:00",
          "encountered_by": "Dr. Hor Mony",
          "title": "Doctor",
          "created_at": "2025-03-17T09:35:00.000+07:00",
          "updated_at": "2025-03-17T10:15:00.000+07:00"
        }
      ],
      "surgeries": [
        {
          "visit_code": "V420650",
          "encounter_code": "E417001",
          "code": "E417004",
          "symptoms": ["Swelling of the abdomen", "Red skin"], //optional
          "theater_name": "Operating Theater 2",
          "service_type": "Laparoscopic Cholecystectomy",
          "started_at": "2025-03-17T10:45:00.000+07:00",
          "ended_at": "2025-04-01T10:15:00.000+07:00",
          "reason": "Symptomatic gallstones with recurrent biliary colic",
          "anesthesia_type": "General Endotracheal",
          "procedure_notes": "",
          //   "procedure_notes": "Patient positioned supine. Pneumoperitoneum established with Veress needle. Four ports were placed. Gallbladder dissected from liver bed with hook cautery. Cystic duct and artery identified, clipped and divided. Gallbladder removed through umbilical port. Hemostasis confirmed. No bile leak. Ports removed under direct visualization. Wounds closed with 3-0 Vicryl and 4-0 Monocryl. Patient tolerated procedure well.",
          "complications": [
            "Mild bleeding from liver bed, controlled with electrocautery"
          ],
          "specimens": [
            "Gallbladder with multiple stones",
            "Cystic fluid sample"
          ],
          "blood_loss": "5cl",
          "surgeon_name": "Dr. Sok Vichet",
          "anesthetist_name": "Dr. Meas Sokunthea",
          "assistant_names": ["Dr. Chhan Rathana", "Nurse Van Bopha"],
          "created_at": "2025-03-17T10:45:00.000+07:00",
          "updated_at": "2025-03-17T11:45:00.000+07:00"
        }
      ],
      "progress_notes": [
        {
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "code": "E317005",
          "started_at": "2025-03-17T16:00:00.000+07:00",
          "ended_at": "2025-03-17T16:15:00.000+07:00",
          "encountered_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "created_at": "2025-03-17T10:35:00.000+07:00",
          "updated_at": "2025-03-17T10:40:00.000+07:00"
        }
      ],
      "soaps": [
        {
          "encounter_code": "E417002",
          "code": "SOA260112",
          "subjective": "Patient reports fever has decreased after first dose of medication. Still experiencing mild headache and fatigue. No chills since this morning. Able to tolerate oral intake well.",
          "objective": "Temperature 37.8°C (down from 38.7°C). Heart rate 85/min. Blood pressure 125/80 mmHg. Skin less jaundiced. Abdomen remains soft with mild tenderness in RUQ.",
          "assessment": "Uncomplicated malaria showing initial response to treatment. Fever trending down. No signs of complications.",
          "plan": "Continue artemether-lumefantrine as prescribed. Encourage oral hydration. Follow-up in clinic in 3 days. Return sooner if symptoms worsen or unable to tolerate medication.",
          "evaluation": null,
          "recorded_at": "2025-03-17T16:10:00.000+07:00",
          "recorded_by": "Dr. Chhun Sovannarith",
          "title": "Doctor"
        }
      ],
      "laboratories": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "request_code": "L00923",
          "requested_at": "2025-03-17T10:30:00.000+07:00",
          "requested_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "collected_at": "2025-03-17T10:30:00.000+07:00",
          "collected_by": "Dr. Chhun Sovannarith",
          "results": [
            {
              "name": "Malaria Blood Smear",
              "category": "Parasitology",
              "value": "Positive for P. falciparum",
              "value_type": "string",
              "value_unit": null,
              "reference_range": "Negative",
              "interpretation": "Positive",
              "verified_at": "2025-03-17T10:50:00.000+07:00",
              "verified_by": "Dr. Meas Chenda",
              "recorded_at": "2025-03-17T10:52:00.000+07:00",
              "recorded_by": "Meas Chandaravuth"
            },
            {
              "name": "Parasitemia",
              "category": "Parasitology",
              "value": 2.5,
              "value_type": "float",
              "value_unit": "%",
              "reference_range": "0",
              "interpretation": "High",
              "verified_at": "2025-03-17T10:50:00.000+07:00",
              "verified_by": "Dr. Meas Chenda",
              "recorded_at": "2025-03-17T10:52:00.000+07:00",
              "recorded_by": "Meas Chandaravuth"
            },
            {
              "name": "Hemoglobin",
              "category": "Hematology",
              "value": 11.2,
              "value_type": "float",
              "value_unit": "g/dL",
              "reference_range": "13.5-17.5",
              "interpretation": "Low",
              "verified_at": "2025-03-17T10:50:00.000+07:00",
              "verified_by": "Dr. Meas Chenda",
              "recorded_at": "2025-03-17T10:52:00.000+07:00",
              "recorded_by": "Meas Chandaravuth"
            }
          ]
        }
      ],
      "imageries": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "request_code": "IM00923",
          "requested_at": "2025-03-17T11:30:00.000+07:00",
          "requested_by": "Dr. Chhun Sovannarith",
          "title": "title",
          "collected_at": "2025-03-17T10:30:00.000+07:00",
          "collected_by": "Dr. Chhun Sovannarith",
          "results": [
            {
              "name": "Brain Scan",
              "category": "CT Scan",
              "images": ["img.com/result2.jpg"],
              "result": "string",
              "conclusion": null,
              "verified_at": "2025-03-17T10:50:00.000+07:00",
              "verified_by": "Dr. Meas Chenda",
              "recorded_at": "2025-03-17T10:52:00.000+07:00",
              "recorded_by": "Meas Chandaravuth"
            }
          ]
        },
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E317001",
          "request_code": "IM23222",
          "requested_at": "2025-03-17T11:35:00.000+07:00",
          "requested_by": "Dr. Chhun Sovannarith",
          "tilte": "Doctor",
          "results": [
            {
              "name": "Adomen Ultrasound",
              "category": "Ultrasound",
              "images": ["img.com/result1.jpg"],
              "result": "string",
              "conclusion": null,
              "verified_at": "2025-03-17T10:50:00.000+07:00",
              "verified_by": "Dr. Meas Chenda",
              "recorded_at": "2025-03-17T10:52:00.000+07:00",
              "recorded_by": "Meas Chandaravuth"
            }
          ]
        }
      ],
      "diagnosis": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": null,
          "diagnosis_type_name": "Primary",
          "diagnosis_code": "B50",
          "diagnosis_name": "Plasmodium falciparum malaria",
          "diagnosis_description": "Plasmodium falciparum malaria with cerebral complications",
          "diagnosed_at": "2025-03-17T10:05:00.000+07:00",
          "diagnosed_by": "Dr. Chhun Sovannarith",
          "title": "Doctor"
        }
      ],
      "consultations": ["Do exercise regularly", "Drink more water"],
      "prescriptions": [
        {
          // medication dispense
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "code": "E317001-2025-03-17",
          "prescribed_at": "2025-03-17T10:10:00.000+07:00",
          "prescribed_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "medications": [
            {
              "code": "MED001",
              "medicine_name": "Artemether-Lumefantrine",
              "strength": "20/120mg",
              "form": "Tablet",
              "method": "Oral",
              "unit": "Tablet",
              "morning": 4,
              "afternoon": 0,
              "evening": 4,
              "night": 0,
              "days": 3,
              "interval": null,
              "note": "Take with food. Complete full course even if feeling better."
            },
            {
              "code": "MED002",
              "medicine_name": "Paracetamol",
              "strength": "500mg",
              "form": "Tablet",
              "method": "Oral",
              "unit": "Tablet",
              "morning": null,
              "afternoon": null,
              "evening": null,
              "night": null,
              "days": 3,
              "interval": "8 hours",
              "note": "Take as needed for fever or pain."
            }
          ]
        },
        {
          // prescription
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": null,
          "code": "PRE-26001",
          "prescribed_at": "2025-03-17T10:10:00.000+07:00",
          "prescribed_by": "Dr. Chhun Sovannarith",
          "title": "Doctor",
          "medications": [
            {
              "code": "MED001",
              "medicine_name": "Artemether-Lumefantrine",
              "strength": "20/120mg",
              "form": "Tablet",
              "method": "Oral",
              "unit": "Tablet",
              "morning": 4,
              "afternoon": 0,
              "evening": 4,
              "night": 0,
              "days": 3,
              "interval": null,
              "note": "Take with food. Complete full course even if feeling better."
            },
            {
              "code": "MED002",
              "medicine_name": "Paracetamol",
              "strength": "500mg",
              "form": "Tablet",
              "method": "Oral",
              "unit": "Tablet",
              "morning": null,
              "afternoon": null,
              "evening": null,
              "night": null,
              "days": 3,
              "interval": "8 hours",
              "note": "Take as needed for fever or pain."
            }
          ]
        }
      ],
      "referrals": {
        "referred_from": null,
        "referred_to": {
          "code": "REF20250317001",
          "referral_number": "HCPP/REF/2025/317",
          "transportation": "Ambulance",
          "reason": "Severe malaria with signs of organ dysfunction requiring ICU care",
          "health_facility": {
            "name": "សេរីសោភ័ណ", //required
            "code": "HEFA-0000001D", //required
            "label": "string", //optional
            "type": "string" //optional
          },

          "has_called": true,
          "caretaker_name": "Sok Channary",
          "caretaker_phone": "012345678",
          "referred_by": "Dr. Chhun Sovannarith",
          "referred_by_phone": "0987654321",
          "referred_at":  "2025-03-18T10:45:00.000+07:00",
          "received_by": null,
          "received_at": null,
          "medications": "Artemether-Lumefantrine 20/120mg (1 dose given at 10:15), IV Artesunate 120mg initiated at 11:00"
        }
      },
      "invoices": [
        {
          "patient_code": "25014827",
          "visit_code": "V420650",
          "encounter_code": "E417002",
          "code": "INV20250317001",
          "payment_type": "HEF",
          "invoice_date": "2025-03-18T09:00:00.000+07:00",
          "total": 120000,
          "created_at": "2025-03-18T09:00:00.000+07:00",
          "updated_at": "2025-03-18T09:00:00.000+07:00",
          "cashier": "Sok Kunthea",
          "services": [
            {
              "invoice_code": "INV20250317001",
              "service_code": "SRV001",
              "service_name": "Blood Smear for Malaria",
              "service_category": "Lab Test",
              "price": 15000,
              "payment": 0,
              "paid": false,
              "discount_type": null,
              "discount": 0
            }
          ],
          "medications": [
            {
              "invoice_code": "INV20250317001",
              "medicine_code": "MED001",
              "medicine_name": "Artemether-Lumefantrine 20/120mg",
              "quantity": 24,
              "unit": "Tablet",
              "price": 1500,
              "payment": 0,
              "paid": false,
              "discount_type": null,
              "discount": 0
            },
            {
              "invoice_code": "INV20250317001",
              "medicine_code": "MED002",
              "medicine_name": "Paracetamol 500mg",
              "quantity": 9,
              "unit": "Tablet",
              "price": 1000,
              "payment": 0,
              "paid": false,
              "discount_type": null,
              "discount": 0
            }
          ]
        }
      ]
    }
  ]
}

Data Validation Rules

Patient Code: Must be unique system-wide and pre-existing
Visit Code: Must be unique per healthcare facility
Encounter Codes: Must be unique within the EMR system
Date Format: Use ISO 8601 format with timezone (YYYY-MM-DDTHH:mm:ss.sss+07:00)
Empty Values: Use null instead of removing fields
Referral Data: Required when patients are transferred between facilities
Required Fields: All codes, timestamps, and identifiers are mandatory
Array Fields: Can be empty arrays [] but should not be null

Response Handling

Success Responses

Complete Success (Status 1)

json

{
  "success": true,
  "http_code": 200,
  "message": "Save successfully",
  "data": {
    "status": 1,
    "uuld": "unique-identifier-12345",
    "visit_code": "V420650"
  }
}

Submission has been completely stored successfully.

Partial Success (Status 3)

json

{
  "success": true,
  "http_code": 200,
  "message": "Save successfully",
  "data": {
    "status": 3,
    "uuld": "unique-identifier-12345",
    "visit_code": "V420650"
  }
}

Submission has been partially stored successfully and is waiting to be updated.

Error Responses

The API returns standard HTTP status codes along with detailed error messages to help diagnose issues.

401 Unauthorized

Returned when the authentication token is missing, invalid, or expired.

json

{
  "success": false,
  "http_code": 401,
  "message": "Unauthenticated",
  "errors": "Invalid or expired token"
}

Common Causes:

Missing or malformed Authorization header
Expired access token
Invalid token format

403 Forbidden

Returned when the authenticated user lacks permission to access the requested resource.

json

{
  "success": false,
  "http_code": 403,
  "message": "Access denied",
  "errors": "You do not have permission to create visits for this facility"
}

Common Causes:

User does not have permission for the specified health facility
System code mismatch
Insufficient role privileges

422 Unprocessable Entity

Returned when the request is well-formed but contains validation errors or business logic violations.

Validation Errors

Occurs when request data fails validation rules.

json

{
  "success": false,
  "http_code": 422,
  "message": "Invalid request data",
  "errors": "The visits.0.admitted_at field is required."
}

Visit Already Submitted

Occurs when attempting to submit a visit that has already been processed by the system.

json

{
  "success": false,
  "http_code": 422,
  "message": "Submit is blocked: Visit Code {visit_code} has already been submitted.",
  "data": null
}

Admission Date Mismatch

Occurs when the admission date in the request differs from the original submission.

json

{
  "success": false,
  "http_code": 422,
  "message": "Submit blocked. Admission date must match the original date.",
  "data": null
}

Duplicate Visit with Same Admission Time

Occurs when a visit already exists for the patient with the same admission date and time.

json

{
  "success": false,
  "http_code": 422,
  "message": "Submit is blocked. The system found an existing visit for this patient with the same admission time. To prevent abnormal claims, this submission has been rejected.",
  "data": null
}

Common Causes:

Invalid date formats
Missing required fields
Duplicate visit submissions
Data integrity violations

500 Internal Server Error

Returned when an unexpected error occurs on the server.

json

{
  "success": false,
  "http_code": 500,
  "message": "Internal server error",
  "errors": "An unexpected error occurred while processing your request"
}

Recommended Action:

Retry the request after a brief delay
If the error persists, contact NPCA technical support with the request details

Rate Limiting

The API implements rate limiting to ensure fair usage:

Authentication endpoints: 60 requests per minute per IP
Data endpoints: 1000 requests per hour per authenticated user
Rate limit headers are included in responses:
- X-RateLimit-Limit: Request limit per time window
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Time when the rate limit resets

Testing and Development

Demo Environment

Base URL: https://demo-authena.pmrs2.org
Test Credentials: Provided by NPCA team
Sample Data: Use the example request bodies provided above

Best Practices

Always validate data before submission
Implement retry logic for transient failures
Store tokens securely and refresh before expiration
Log API responses for debugging and monitoring
Use proper error handling for all response codes
Test with sample data before production deployment

API Endpoints ​

Public Endpoints ​

1. Get Standard Data ​

Data Endpoints ​

Required Headers for Data Endpoints ​

2. Search Beneficiary ​

3. Submit Visit Data ​

4. Get Processing Status ​

Request Body Structure ​

Data Validation Rules ​

Response Handling ​

Success Responses ​

Complete Success (Status 1) ​

Partial Success (Status 3) ​

Error Responses ​

401 Unauthorized ​

403 Forbidden ​

422 Unprocessable Entity ​

Validation Errors ​

Visit Already Submitted ​

Admission Date Mismatch ​

Duplicate Visit with Same Admission Time ​

500 Internal Server Error ​

Rate Limiting ​

Testing and Development ​

Demo Environment ​

Best Practices ​

API Endpoints

Public Endpoints

1. Get Standard Data

Data Endpoints

Required Headers for Data Endpoints

2. Search Beneficiary

3. Submit Visit Data

4. Get Processing Status

Request Body Structure

Data Validation Rules

Response Handling

Success Responses

Complete Success (Status 1)

Partial Success (Status 3)

Error Responses

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Validation Errors

Visit Already Submitted

Admission Date Mismatch

Duplicate Visit with Same Admission Time

500 Internal Server Error

Rate Limiting

Testing and Development

Demo Environment

Best Practices