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.
Request access
Keys are issued to named organizations after review; nothing is granted automatically.
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.
Step 2: Ministry review
A Federal or Regional admin reviews the scope and purpose, and sets the granted permissions, geographic restrictions and key settings.
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.
X-Api-Key: <your-api-key># Set these on your integration server.
export MFR_API="https://mfr.moh.gov.et"
export MFR_API_KEY="<your-api-key>"Permissions
Permissions are granted individually. Existing keys keep their current permissions; new scopes are not added automatically.
| Scope | Use |
|---|---|
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 search
Requires facilities:read and returns paginated facility rows. pageNumber is at least 1 and showPerPage is limited to 1–100. Approved geographic restrictions apply automatically; conflicting location filters return 403.
POST /api/public/v1/facilities/search
X-Api-Key: <your-api-key>
Content-Type: application/jsontype FacilityParameters = {
name?: string;
pageNumber?: number;
showPerPage?: number;
statusId?: number[];
ownershipId?: number[];
regionId?: number[];
zoneId?: number[];
woredaId?: number[];
facilityTypeId?: number[];
operationalStatusId?: number[];
constructionStatusId?: number[];
clinicalServiceId?: number[];
diagnosticAndImagingServiceId?: number[];
twentyFourHourServiceOfferId?: number[];
supportServiceId?: number[];
};type FacilitySearchRow = {
id: number;
name?: string | null;
status?: string | null;
operationalStatus?: string | null;
facilityType?: string | null;
parentFacilityType?: string | null;
ownership?: string | null;
region?: string | null;
zone?: string | null;
woreda?: string | null;
totalCount: number;
pageCount: number;
};curl -X POST "$MFR_API/api/public/v1/facilities/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MFR_API_KEY" \
-d '{"pageNumber":1,"showPerPage":25,"name":"clinic"}'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.
GET /api/public/v1/facilities/{id}
X-Api-Key: <your-api-key>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 };GET /api/public/v1/facilities/{id}/services
X-Api-Key: <your-api-key>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.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
| Method | Path | Purpose |
|---|---|---|
| POST | /facilities/search | Paginated search with a compact response |
| GET | /facilities/{id} | Profile by numeric facility ID |
| GET | /facilities/dhis2/{dhis2id} | Profile by DHIS2 ID |
| GET | /facilities/{id}/services | Services, infrastructure, staffing and inventory by numeric ID |
| GET | /facilities/dhis2/{dhis2id}/services | Services, infrastructure, staffing and inventory by DHIS2 ID |
Facility compatibility routesfacilities:read
| Method | Path | Purpose |
|---|---|---|
| GET | /Facility?id={id} | Compact profile by numeric facility ID |
| GET | /Facility/{dhis2id} | Compact profile by DHIS2 ID |
| POST | /Facility/GetFacilities | Search with existing filters and list format |
| POST | /Facility/GetFacilitiesZen | Facility list with coordinates and paging fields |
| GET | /Facility/GetFacilitiesCount | Count with optional geographic filters |
| GET | /Facility/GetLookupsUsageCount?name={name}&id={id} | Facility usage count for a lookup value |
| GET | /Facility/All | Compact facility profiles with existing query filters |
Lookups and facility typeslookups:read
| Method | Path | Purpose |
|---|---|---|
| GET | /Lookup?name={name}&id={id} | Lookup values; id is optional |
| GET | /RequestReasons?kind=data|api | Active intended uses for data or API requests |
| GET | /Lookup/GetFacilityType | Top-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/GetOwnership | Ownership values |
| POST | /Lookup/QualificationsByFacilityType | Qualifications for a type and optional subtypes |
Geographic reference datalocations:read
| Method | Path | Purpose |
|---|---|---|
| GET | /Location/Regions | Regions |
| GET | /Location/Zones | Zones |
| GET | /Location/GetZoneByRegion?RegionId={id} | Zones within a region |
| GET | /Location/Woredas | Woredas |
| GET | /Location/GetWoredaByZone?ZoneId={id} | Woredas within a zone |
Reportsreports:read
| Method | Path | Purpose |
|---|---|---|
| GET | /Report/Dashboard | Summary rows with type, name and count |
| POST | /Report/Counts | Counts for the supplied facility filters |
| GET | /Report/RecentFacilities | Recent 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.
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=1POST /api/public/v1/Lookup/QualificationsByFacilityType
Content-Type: application/json
{"facilityTypeId":1,"facilitySubTypeIds":[]}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,WoredaandFacility, 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.
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.
| Status | Meaning |
|---|---|
400 | Missing or invalid request body |
401 | Missing, invalid, inactive, or expired API key |
403 | Required permission is missing or the request is outside the approved geography |
404 | Facility not found for the detail endpoint |
429 | The API key has reached a configured request limit; pause requests and use backoff |
500 | The 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.
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
/Facilitydetail and/Facility/Allroutes return the same compact profile as the plural detail routes. Update response parsing when migrating: related facilities are smallreportsToandreferralLinkageobjects, and service, staffing and infrastructure lists moved to/facilities/{id}/services. Lookups containid,nameandcode; 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.