API v1 integration guide

Connect approved integrations to facility data, geographic references, lookups and reports with an API key. This guide covers the v1 routes, the response contract and how to move an existing integration.

Quick reference
Everything a first call needs. Keys are issued after review; four permissions, each approved individually.
Base URL
https://mfr.moh.gov.et/api/public/v1
Authentication
X-Api-Key: <your-api-key>
Example
curl "https://mfr.moh.gov.et/api/public/v1/facilities/123" -H "X-Api-Key: $MFR_API_KEY"

Request access

Keys are issued to named organizations after review; nothing is granted automatically.

  1. Step 1: Submit the request form

    Give your organization, the permissions you need, the geographic coverage and the intended use on the API access request form. Facility read access is selected by default. Bulk files use reviewed data requests.

  2. Step 2: Ministry review

    A Federal or Regional admin reviews the scope and purpose, and sets the granted permissions, geographic restrictions and key settings.

  3. Step 3: Key delivered by email

    Approved keys go to the address on the request. Check your spam folder, keep the key private, and contact support to change an existing key's permissions.

Requests sent through the API use a requestedScopes list and a fresh MoH Cap CAPTCHA token in the X-Cap-Token header; onboarding stays at POST /api/ApiAccess/Requests and needs no API key.

Authentication

Send one X-Api-Key header with your approved key on every keyed request over HTTPS.

Header
X-Api-Key: <your-api-key>
Server configuration
# Set these on your integration server.
export MFR_API="https://mfr.moh.gov.et"
export MFR_API_KEY="<your-api-key>"
Keep the key on the server
Do not embed it in browser code, URLs or shared files. Request only the permissions your integration needs, and contact support to replace a key that is no longer secure.

Permissions

Permissions are granted individually. Existing keys keep their current permissions; new scopes are not added automatically.

ScopeUse
facilities:readSelected by default
Facility search and profiles. Search facilities, view profiles, and retrieve facility lists and counts.
lookups:read
Lookups and facility types. Retrieve facility types, ownership categories, qualifications and other reference values.
locations:read
Geographic reference data. Retrieve region, zone and woreda lists for filters and location selections.
reports:read
Reports and summaries. Retrieve dashboard summaries, counts, recent facilities and geographic reports.

Facility profile

Requires facilities:read and returns identifiers, address, coordinates, classification labels, official facility contact information, the technical manager on record and small references to the reporting and referral facilities. Services are a separate route (below). Use a numeric ID or /facilities/dhis2/{dhis2id} for a DHIS2 identifier; requests outside an approved geographic restriction return 403. Blank text is returned as null.

Request
GET /api/public/v1/facilities/{id}
X-Api-Key: <your-api-key>
Response
type FacilityDetail = {
  id: number;
  name?: string | null;
  otherName?: string | null;
  hmisCode?: string | null;
  ethiopianNationalFacilityId?: string | null;
  facilityId?: string | null;
  oldName?: string | null;
  dhis2Id?: string | null;
  reportsTo?: FacilityReference | null;      // null when absent, inactive or a duplicate
  referralLinkage?: FacilityReference | null;
  status?: string | null;
  operationalStatus?: string | null;
  facilityType?: string | null;
  parentFacilityType?: string | null;
  facilityTypes: { id: number; name?: string | null; code?: string | null }[];  // every type and subtype
  ownership?: string | null;
  settlement?: string | null;                // "Urban" or "Rural"
  yearOpened?: string | null;                // ISO date
  catchmentPopulation?: number | null;
  isPrimaryHealthCareUnit?: boolean | null;
  yearLicenseLastRenewed?: string | null;    // ISO date
  closedDate?: string | null;                // as recorded; read with operationalStatus
  suspensionStartDate?: string | null;
  suspensionEndDate?: string | null;
  region?: string | null;
  zone?: string | null;
  woreda?: string | null;
  city?: string | null;
  kebele?: string | null;
  specificAreaName?: string | null;
  streetNumber?: string | null;
  houseNumber?: string | null;
  latitude?: number | null;
  longitude?: number | null;
  altitude?: number | null;
  phoneNumber?: string | null;
  email?: string | null;
  website?: string | null;
  fax?: string | null;
  postalAddress?: string | null;
  // Technical leader of an actively licensed facility, otherwise the head of facility.
  pocName?: string | null;
  pocQualification?: string | null;
  pocRegistrationNumber?: string | null;
  pocPhoneNumber?: string | null;
  pocEmail?: string | null;
};

type FacilityReference = { id: number; name?: string | null; hmisCode?: string | null; dhis2Id?: string | null };
Services request
GET /api/public/v1/facilities/{id}/services
X-Api-Key: <your-api-key>
Services response
type Lookup = { id: number; name?: string | null; code?: string | null };

type FacilityServices = {
  facilityId: number;
  clinical: Lookup[];                // ids join to the Lookup lists and search filters
  diagnosticAndImaging: Lookup[];
  support: Lookup[];
  twentyFourHour: Lookup[];
  otherDiagnosticAndImagingServices?: string | null;  // free text
  constructionStatus?: string | null;                 // e.g. "Completed", "Under Construction"
  power: Lookup[];
  water: Lookup[];
  ictInfrastructure: Lookup[];
  wasteManagement: Lookup[];
  communications: Lookup[];
  staffing: (Lookup & { count: number })[];  // group by id; 0 means none
  staffingSummary: Record<string, number | null>;     // the record's own 18 counts: nurses, midwives, ...
                                                      // a separate source; do not add to staffing
  beds: { inpatient?: number | null; emergency?: number | null; maternity?: number | null };
  rooms: Record<string, number | null>;              // opd, ipd, operatingTheatres, icu, ...
  roomAvailability: Record<string, boolean | null>;  // reception, inpatient, delivery, ...
  transport: Record<string, number | boolean | null>;
  ict: Record<string, number | boolean | null>;      // servers, desktops, internet4G, ...
  sanitation: Record<string, boolean | null>;        // flushToPitLatrine, compostingToilet, ...
};
// null means not recorded; 0 or false means none.
Example (curl)
curl "$MFR_API/api/public/v1/facilities/123" \
  -H "X-Api-Key: $MFR_API_KEY"

Endpoint directory

The v1 surface contains 29 retrieval operations. Add /api/public/v1 to each path; POST operations here retrieve data with a JSON body. The API reference lists every parameter and response field.

Facility search and profilesfacilities:read

MethodPathPurpose
POST/facilities/searchPaginated search with a compact response
GET/facilities/{id}Profile by numeric facility ID
GET/facilities/dhis2/{dhis2id}Profile by DHIS2 ID
GET/facilities/{id}/servicesServices, infrastructure, staffing and inventory by numeric ID
GET/facilities/dhis2/{dhis2id}/servicesServices, infrastructure, staffing and inventory by DHIS2 ID

Facility compatibility routesfacilities:read

MethodPathPurpose
GET/Facility?id={id}Compact profile by numeric facility ID
GET/Facility/{dhis2id}Compact profile by DHIS2 ID
POST/Facility/GetFacilitiesSearch with existing filters and list format
POST/Facility/GetFacilitiesZenFacility list with coordinates and paging fields
GET/Facility/GetFacilitiesCountCount with optional geographic filters
GET/Facility/GetLookupsUsageCount?name={name}&id={id}Facility usage count for a lookup value
GET/Facility/AllCompact facility profiles with existing query filters

Lookups and facility typeslookups:read

MethodPathPurpose
GET/Lookup?name={name}&id={id}Lookup values; id is optional
GET/RequestReasons?kind=data|apiActive intended uses for data or API requests
GET/Lookup/GetFacilityTypeTop-level facility types
GET/Lookup/GetFacilityTypeByParent?ParentFacilityTypeId={id}Children of a facility type
GET/Lookup/ProfessionalRequirements?facilityTypeId={id}&subTypeId={id}Required staff for a type and optional sub-type
GET/Lookup/GetOwnershipOwnership values
POST/Lookup/QualificationsByFacilityTypeQualifications for a type and optional subtypes

Geographic reference datalocations:read

MethodPathPurpose
GET/Location/RegionsRegions
GET/Location/ZonesZones
GET/Location/GetZoneByRegion?RegionId={id}Zones within a region
GET/Location/WoredasWoredas
GET/Location/GetWoredaByZone?ZoneId={id}Woredas within a zone

Reportsreports:read

MethodPathPurpose
GET/Report/DashboardSummary rows with type, name and count
POST/Report/CountsCounts for the supplied facility filters
GET/Report/RecentFacilitiesRecent facility records
GET/Report/GeoLocations/{type}Region, Zone, Woreda or Facility point rows

Reference data and reports

Lookup and location lists provide the values for filters and selections. Geographic lists are available across the register with locations:read; facility and report requests stay within your approved geography.

Locations and lookups
GET /api/public/v1/Location/Regions
GET /api/public/v1/Location/GetZoneByRegion?RegionId=1
GET /api/public/v1/Lookup?name=Ownership
GET /api/public/v1/Lookup/GetFacilityTypeByParent?ParentFacilityTypeId=1
Qualifications by facility type
POST /api/public/v1/Lookup/QualificationsByFacilityType
Content-Type: application/json

{"facilityTypeId":1,"facilitySubTypeIds":[]}
Reports
GET /api/public/v1/Report/Dashboard?regionId=1
GET /api/public/v1/Report/UnclassifiedFacilities
GET /api/public/v1/Report/GeoLocations/Region?regionId=1

POST /api/public/v1/Report/Counts
Content-Type: application/json

{"regionId":[1]}
  • To build a facility-type hierarchy, fetch the top-level types, then the children of each selected parent.
  • Geographic report types are Region, Zone, Woreda and Facility, supplied in the path; use geographic filters to focus results.
  • Report lists carry no pagination metadata. Coordinate rows can be converted to your map format of choice.

Response envelope

Every retrieval route returns the standard MFR envelope; result: 0 means success.

Envelope
type MfrResponse<T> = {
  result: number;
  message?: string | null;
  model?: T | null;
};

Check both the HTTP status and result: some reference-data requests return a nonzero result with HTTP 200, which is a failed request rather than an empty one. Facility search rows carry totalCount and pageCount; other lists may have different structures.

Error codes

Correct credentials or permissions before retrying 401 or 403 responses. For 429, pause and back off within the limits agreed for your key; a retry time may not be included.

StatusMeaning
400Missing or invalid request body
401Missing, invalid, inactive, or expired API key
403Required permission is missing or the request is outside the approved geography
404Facility not found for the detail endpoint
429The API key has reached a configured request limit; pause requests and use backoff
500The service could not complete the request

Contact support if a limit or a repeated error prevents normal use.

Migration and exports

Keep the HTTP method and replace /api/ with /api/public/v1/ for the corresponding compatibility route. Preserve its query parameters or JSON body and add the API-key header.

Route mapping
GET /api/Facility?id=123
  → GET /api/public/v1/Facility?id=123

POST /api/Facility/GetFacilities
  → POST /api/public/v1/Facility/GetFacilities

GET /api/Location/Regions
  → GET /api/public/v1/Location/Regions
  • The singular /Facility detail and /Facility/All routes return the same compact profile as the plural detail routes. Update response parsing when migrating: related facilities are small reportsTo and referralLinkage objects, and service, staffing and infrastructure lists moved to /facilities/{id}/services. Lookups contain id, name and code; locations also retain parent IDs where applicable. Legacy /api/ contracts remain available during transition.
  • Archived facilities and direct XLSX, CSV and JSON exports are unavailable through the keyed API. For bulk files, request a reviewed facility extract.
  • Contact support for migration timing and any permission changes your integration needs.

Data freshness and acceptable use

Data reflects registry updates and each endpoint's refresh cycle. Report results may be cached, so a response is not a guarantee of an immediate change in the register.

  • Respect response cache headers and the usage terms agreed for your integration.
  • Keep source attribution to the Ethiopian Ministry of Health and record when you retrieved data.
  • Use or share data only within your approved purpose and geography.
  • Describe a registry count according to the filters it was taken with.

Next steps

Request a key, browse every operation in the API reference, or ask for help with an integration.