Available scopes

Permissions are granted individually. Existing keys retain their current permissions; new scopes are not added automatically. A standard access request defaults to facilities:read.

Endpoint directory

The v1 surface contains 28 retrieval operations. Add the prefix /api/public/v1 to each path below. POST operations in this directory retrieve data using a JSON request body. Expand a group for its routes; consult the API reference for all parameters and response fields.

Reference data and reports

Lookup and location lists provide reference values for filters and selections. Geographic reference lists are available across the register with locations:read; facility and report requests remain subject to your approved geography. To build a facility-type hierarchy, fetch the top-level types, then request the children of each selected parent.

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

POST /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/GeoLocations/Region?regionId=1

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

{"regionId":[1]}

Include your API-key header on each request. Replace example IDs with reference values appropriate to your integration. Geographic report types are Region, Zone, Woreda and Facility, supplied in the path. Use geographic filters to focus results. These report lists do not include pagination metadata; coordinate data can be converted to your application’s preferred map format.

Migration and exports

For an existing integration, 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. Compatibility routes retain established response formats.

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 retain the established facility response. The plural /facilities/search and /facilities/… profile routes offer compact responses with classification and location labels. Choose the documented contract that matches your integration; the two formats are not interchangeable.

Exports require the separate facilities:export permission and accept a JSON filter body with optional columns. Successful responses contain the XLSX, CSV or JSON download, rather than the standard retrieval envelope. Follow the selected export’s schema and content type. Requesting read access does not automatically grant export access.

Access-request onboarding stays at POST /api/ApiAccess/Requests and does not require an API key. Contact support for migration timing and any permission changes your integration needs. A fresh MoH Cap CAPTCHA token is required in the X-Cap-Token header.

Response envelope

JSON retrieval routes return the standard MFR envelope. result: 0 means success. Check both the HTTP status and result: some reference-data requests can return a nonzero result with HTTP 200. Treat that as a failed request, rather than an empty result. Facility search rows carry totalCount and pageCount; other lists may have different structures. Export successes return file content directly.

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