GNHR API Documentation

Table of Contents

1. Registry Households — GET
1b. Registry Households — PUT (Cases)
1c. Registry Cases — POST
2. Registry Members Factory
3. Locations Factory
4. SP MEMIS Statistics (HR13.1)
5. API Endpoints Summary
6. Important Notes

Introduction

This document provides comprehensive documentation for making HTTP GET and PUT requests to the GNHR API endpoints. All endpoints support HTTPS and require proper authentication where applicable.

Base URL:

https://registry.mogcsp.gov.gh

Replace with your actual domain name

Accessing Personal Identifiable Information (PII):

--header 'Authorization: ••••••'

All requests for PII on households/members will require a Bearer Token Auth type with a base64 encoded GHNR assigned authId and authSecret

Registry Households Factory

GET /api/v2/households

Description

Retrieves household data with associated members from the registry. This endpoint supports filtering by location, categorization, optional creation-time lower bound (startDate), optional free-text search on household head and contact fields (search), and pagination. Data can be retrieved from either the current registry or legacy consolidated tables. Authentication: every request must include an Authorization: Bearer header; the token must be valid for the partnerCode query parameter (see the Introduction and Headers below).

Parameters

Parameter	Type	Required	Default	Description	Example
`partnerCode`	string	Required	-	Partner code (e.g. 'LEAP', 'NHIA'); must match the partner associated with the `Authorization` Bearer token	LEAP
`source`	string	Optional	-	Location type filter: 'R' (Region), 'D' (District), 'C' (Community), 'H' (Household UUID)	R
`sourceCode`	string	Optional	-	Location code corresponding to the source type	01
`offset`	integer	Optional	0	Number of records to skip for pagination	0
`limit`	integer	Optional	100	Maximum number of records to return	100
`readyToShareOnly`	string	Optional	yes	Filter by ready to share status: 'yes' or 'no'. Not applied when `fromLegacy=yes`	yes
`categorization`	string	Optional	-	Poverty categorization filter. Can be single value or comma-separated list	EXTREMELY_POOR or EXTREMELY_POOR,POOR
`startDate`	string	Optional	-	Only households with `created_ts` on or after this instant. Use `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss` or with fractional seconds `YYYY-MM-DD HH:mm:ss.ms`. Values that do not match this pattern are ignored (no date filter). Echoed in the response as `startDate` when provided.	2025-03-20 or 2025-03-20 20:01:59.517
`search`	string	Optional	-	Substring match on the whole string; ignored if longer than 50 characters. Matches any of: household head last name, first name, other names, popular name; household address; household phone; main and other phone numbers; Ezwich card number and card name. Applied in the household uuid filter. Echoed in the response as `search` when provided.	0244123456 or Main St
`fromLegacy`	string	Optional	no	Retrieve data from legacy consolidated tables: 'yes' or 'no'	no

Headers

Header	Required	Description
`Authorization`	Required	`Bearer` token (GNHR-issued); validated against `partnerCode`
`Content-Type`	Optional	Typically `application/json` for GET requests

cURL Examples

Each example includes the required Authorization header. Replace <your_token> with your active Bearer token.

Example 1: Basic Request

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 2: Filter by Region with Pagination

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&source=R&sourceCode=01&offset=0&limit=50"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 3: Filter by Categorization

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&categorization=EXTREMELY_POOR,POOR&readyToShareOnly=yes"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 4: Get Specific Household

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&source=H&sourceCode=household-uuid-123"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 5: From Legacy Tables

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&fromLegacy=yes&source=D&sourceCode=0101"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 6: Created on or after a date

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&startDate=2025-03-20&offset=0&limit=50"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 7: Free-text search on household fields

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP&search=0244123456&source=D&sourceCode=0101"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Sample Response

Success Response (200 OK)

                                        {
                                        "successful": true,
                                        "quantity": 150,
                                        "offset": 0,
                                        "limit": 100,
                                        "fromLegacy": false,
                                        "startDate": null,
                                        "search": null,
                                        "data": [
                                        {
                                        "id": 1,
                                        "uuid": "hh-uuid-123",
                                        "region_code": "01",
                                        "district_code": "0101",
                                        "community_code": "010101",
                                        "QA_STAGE": "GNHR_OK",
                                        "hh_leap_id": "leap-123",
                                        "categorization": "EXTREMELY_POOR",
                                        "readyToShare": "Y",
                                        "status": "ACTIVE",
                                        "categorization_score": 85.5,
                                        "members": [
                                        {
                                        "member_id": "mm-001",
                                        "member_uuid": "member-uuid-456",
                                        "household_uuid": "hh-uuid-123",
                                        "mm_member_firstname": "John",
                                        "mm_member_lastname": "Doe",
                                        "mm_member_gender": "M",
                                        "mm_dob": "1990-01-15"
                                        }
                                        ]
                                        }
                                        ]
                                        }
                                    

Error Response (400 Bad Request)

                                        {
                                        "Error": "Missing required field"
                                        }
                                    

Registry Households — Create Case (PUT)

PUT /api/v2/households

Description

Submits a registry case for GNHR review. The request does not update household or member registry directly; it creates a case for investigation. Authentication: requires Authorization: Bearer validated against partnerCode. Important: send the request over HTTPS. For location/community investigations (including communityCode), use POST /api/registry-cases instead.

Query Parameters

Parameter	Type	Required	Description	Example
`partnerCode`	string	Required	Partner code; must match the Bearer token. May also be sent in the JSON body.	LEAP

Request Body (JSON)

Field	Type	Required	Description
`action`	string	Required	One of: `CASE_MANAGEMENT`, `HOUSEHOLD_UPDATE`, `MEMBER_UPDATE`.
`householdUUID`	string	Conditional	Required for `HOUSEHOLD_UPDATE`. At least one of `householdUUID` or `memberUUID` required.
`memberUUID`	string	Conditional	Required for `MEMBER_UPDATE`.
`data`	object	Required	Must include at least one non-null field.

Headers

Header	Required	Description
`Authorization`	Required	`Bearer` token validated against `partnerCode`
`Content-Type`	Required	`application/json`

cURL Examples

Example 1: Case management

                                    curl -X PUT "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"CASE_MANAGEMENT","householdUUID":"hh-uuid-123","memberUUID":"member-uuid-456","data":{"purpose":"Escalate data quality issue"}}'
                                

Example 2: Household update case

                                    curl -X PUT "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"HOUSEHOLD_UPDATE","householdUUID":"hh-uuid-123","memberUUID":"member-uuid-456","data":{"purpose":"Correct phone","hh_main_phone_number":"233244740439"}}'
                                

Example 3: Member update case

                                    curl -X PUT "https://registry.mogcsp.gov.gh/api/v2/households?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"MEMBER_UPDATE","householdUUID":"hh-uuid-123","memberUUID":"member-uuid-456","data":{"purpose":"Update NHIS","mm_member_nhis_card_number":"NHIS-123456"}}'
                                

Sample Responses

Success (201 Created)

{"successful":true,"caseReference":42}

Validation (400)

{"successful":false,"error":"Invalid action","allowed":["CASE_MANAGEMENT","HOUSEHOLD_UPDATE","MEMBER_UPDATE"]}

Unauthorized (401)

{"error":{"code":1001,"message":"Access denied. Please check your authId, authSecret and ensure your IP address is whitelisted"}}

HTTP Status Codes

Code	Meaning
201	Case created; `caseReference`
400	Validation failed (missing fields, invalid action, etc.)
401	Invalid Bearer token for `partnerCode`
422	Failed to insert into `registry_cases`

Registry Cases — Create Case (POST)

POST /api/registry-cases

Description

Creates a row in GNHR_DATA.dbo.registry_cases for GNHR review. The request body matches the case-creation contract used by PUT /api/v2/households, with an additional communityCode field persisted to the community_code column (required for LOCATION_CASE). Authentication: requires Authorization: Bearer validated against partnerCode (partner firm credentials). Admin UI: the portal cases page uses GET/PUT on the same path with session token header for list and status updates only. Important: send partner integrations over HTTPS.

Query Parameters

Parameter	Type	Required	Description	Example
`partnerCode`	string	Required	Partner code; must match the Bearer token. May also be sent in the JSON body.	GNHR
`communityCode`	string	Conditional	GNHR community code. Required when `action` is `LOCATION_CASE`. May also be sent in the body as `community_code`.	03-02-072

Request Body (JSON)

Field	Type	Required	Description
`action`	string	Required	One of: `CASE_MANAGEMENT`, `HOUSEHOLD_UPDATE`, `MEMBER_UPDATE`, `LOCATION_CASE`. Stored in `type`.
`householdUUID`	string	Conditional	Required for `HOUSEHOLD_UPDATE`. For other actions (except `LOCATION_CASE`), at least one of `householdUUID` or `memberUUID` is required. Stored in `household_uuid`.
`memberUUID`	string	Conditional	Required for `MEMBER_UPDATE`. Stored in `member_uuid`.
`communityCode`	string	Conditional	Required for `LOCATION_CASE`. GNHR `communityCode` from `Communities`. Stored in `community_code`.
`data`	object	Required	Case details. Must include `purpose` (string). For `HOUSEHOLD_UPDATE` and `MEMBER_UPDATE`, must contain at least one additional non-null field. Serialized into `case_payload` with the request metadata.
`data.purpose`	string	Required	Human-readable reason for the case. Also stored in the `purpose` column.

Headers

Header	Required	Description
`Authorization`	Required	`Bearer` token validated against `partnerCode`
`Content-Type`	Required	`application/json`

cURL Examples

Example 1: Case management

                                    curl -X POST "https://registry.mogcsp.gov.gh/api/registry-cases?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"CASE_MANAGEMENT","householdUUID":"hh-uuid-123","memberUUID":"member-uuid-456","data":{"purpose":"Escalate data quality issue"}}'
                                

Example 2: Household update case

                                    curl -X POST "https://registry.mogcsp.gov.gh/api/registry-cases?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"HOUSEHOLD_UPDATE","householdUUID":"hh-uuid-123","data":{"purpose":"Correct phone","hh_main_phone_number":"233244740439"}}'
                                

Example 3: Member update case

                                    curl -X POST "https://registry.mogcsp.gov.gh/api/registry-cases?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"MEMBER_UPDATE","memberUUID":"member-uuid-456","data":{"purpose":"Update NHIS","mm_member_nhis_card_number":"NHIS-123456"}}'
                                

Example 4: Location / community investigation

                                    curl -X POST "https://registry.mogcsp.gov.gh/api/registry-cases?partnerCode=GNHR" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>" \
                                    -d '{"action":"LOCATION_CASE","communityCode":"03-02-072","data":{"purpose":"Investigate Example Community.:verify the region, district and other data","communityName":"Example Community","districtCode":"03-02"}}'
                                

Sample Responses

Success (201 Created)

{"successful":true,"caseReference":42}

caseReference is the new registry_cases.id.

Validation (400)

{"successful":false,"error":"communityCode is required for LOCATION_CASE"}

Invalid action (400)

{"successful":false,"error":"Invalid action","allowed":["CASE_MANAGEMENT","HOUSEHOLD_UPDATE","MEMBER_UPDATE","LOCATION_CASE"]}

Unauthorized (401)

{"error":{"code":1001,"message":"Access denied. Please check your authId, authSecret and ensure your IP address is whitelisted"}}

HTTP Status Codes

Code	Meaning
201	Case created; response includes `caseReference`
400	Validation failed (missing fields, invalid action, missing purpose, etc.)
401	Invalid Bearer token for `partnerCode`
422	Failed to insert into `registry_cases`
405	Unsupported HTTP method

Database columns populated

Column	Source
`type`	`action`
`firm_code`	`partnerCode`
`purpose`	`data.purpose`
`case_payload`	JSON snapshot of action, UUIDs, communityCode, purpose, assigned_to, and `data`
`status`	`status` (default `P`)
`assigned_to`	`assigned_to` / `assignedTo`
`household_uuid`	`householdUUID`
`member_uuid`	`memberUUID`
`community_code`	`communityCode` / `community_code`
`created_ts`	Server default (UTC)

Registry Members Factory

GET /api/v2/members

Description

Retrieves household member data from the registry. This endpoint returns individual member records with associated household categorization. Supports filtering by location, categorization, optional free-text search across member fields, and pagination. Authentication: every request must include an Authorization: Bearer header; the token must be valid for the partnerCode query parameter (see the Introduction and Headers below).

Parameters

Parameter	Type	Required	Default	Description	Example
`partnerCode`	string	Required	-	Partner code (e.g. 'LEAP', 'NHIA'); must match the partner associated with the `Authorization` Bearer token	LEAP
`source`	string	Optional	-	Location type filter: 'R' (Region), 'D' (District), 'C' (Community)	D
`sourceCode`	string	Optional	-	Location code corresponding to the source type	0101
`offset`	integer	Optional	0	Number of records to skip for pagination	0
`limit`	integer	Optional	200	Maximum number of records to return	200
`categorization`	string	Optional	-	Poverty categorization filter. Can be single value or comma-separated list	EXTREMELY_POOR or EXTREMELY_POOR,POOR
`search`	string	Optional	-	Substring match on the whole string; ignored if longer than 50 characters. Matches any of: member last name, first name, other name, popular name, date of birth (as text), main phone, NHIS card number, NHIS full name, Ghana Card number, Ghana Card full name. Returned JSON echoes the submitted value in `search` when provided.	0244123456
`fromLegacy`	string	Optional	false	Retrieve data from legacy consolidated tables: 'yes' or 'no'	no

Headers

Header	Required	Description
`Authorization`	Required	`Bearer` token (GNHR-issued); validated against `partnerCode`

cURL Examples

Each example includes the required Authorization header. Replace <your_token> with your active Bearer token.

Example 1: Basic Request

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=LEAP" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 2: Filter by District

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=LEAP&source=D&sourceCode=0101&offset=0&limit=100"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 3: Filter by Categorization with Pagination

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=LEAP&categorization=EXTREMELY_POOR&offset=0&limit=50"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 4: Multiple Categorizations

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=LEAP&categorization=EXTREMELY_POOR,POOR&source=R&sourceCode=01"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 5: NHIA Partner Code

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=NHIA&source=C&sourceCode=010101"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Example 6: Free-text search

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/members?partnerCode=LEAP&search=0244123456&offset=0&limit=50"
                                    \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Sample Response

Success Response (200 OK)

                                        {
                                        "successful": true,
                                        "quantity": 450,
                                        "offset": 0,
                                        "limit": 200,
                                        "search": null,
                                        "data": [
                                        {
                                        "member_uuid": "member-uuid-456",
                                        "mm_member_lastname": "Doe",
                                        "mm_member_firstname": "John",
                                        "mm_member_othername": "Kwame",
                                        "mm_member_photo": "photo-url-123",
                                        "mm_member_gender": "M",
                                        "mm_dob": "1990-01-15",
                                        "mm_member_main_phone_number": "0244123456",
                                        "mm_member_nhis_policy_expiry": "2024-12-31",
                                        "mm_member_nhis_policy_validity_date": "2023-01-01",
                                        "mm_member_nhis_card_number": "NHIS123456",
                                        "mm_member_nhis_full_name": "John Kwame Doe",
                                        "mm_member_nhis_front_photo": "nhis-front-url",
                                        "mm_member_nhis_back_photo": "nhis-back-url",
                                        "mm_region_code": "01",
                                        "mm_district_code": "0101",
                                        "mm_community_code": "010101",
                                        "categorization": "EXTREMELY_POOR",
                                        "household_uuid": "hh-uuid-123"
                                        }
                                        ]
                                        }
                                    

Error Response (400 Bad Request)

                                        {
                                        "Error": "Missing required field"
                                        }
                                    

Locations Factory

GET /api/locations or /api/v2/locations

Description

Retrieves location data including regions, districts, communities, enumeration areas, and LEAP communities. Supports various location types and filtering options for hierarchical location data.

Parameters

Parameter	Type	Required	Default	Description	Example
`type`	string	Required	-	Location type (see Location Type Reference table below)	R
`source`	string	Optional	-	Source filter for LEAP communities: 'R' (Region), 'D' (District), 'ID' (Community ID)	R
`parent_code`	string	Optional	-	Parent location code (required for districts, communities, EAs, etc.)	01
`offset`	integer	Optional	0	Number of records to skip (currently not fully implemented)	0
`limit`	integer	Optional	0	Maximum number of records to return (currently not fully implemented)	0

Location Type Reference

Type Code	Description	Requires parent_code
`R`	All Regions	No
`D`	Districts by Region	Yes (Region Code)
`C`	Communities by District	Yes (District Code)

cURL Examples

Example 1: Get All Regions

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/locations?type=R" \
                                    -H "Content-Type: application/json"
                                

Example 2: Get Districts by Region

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/locations?type=D&parent_code=01" \
                                    -H "Content-Type: application/json"
                                

Example 3: Get Communities by District

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/locations?type=C&parent_code=0101"
                                    \
                                    -H "Content-Type: application/json"
                                

Example 4: Get LEAP Communities Mapped

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/locations?type=LC_M&source=R&parent_code=01" \
                                    -H "Content-Type: application/json"
                                

Example 5: Get Regions with Targets

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/locations?type=R_T" \
                                    -H "Content-Type: application/json"
                                

Example 6: Get Enumeration Areas

                                    curl -X GET "https://registry.mogcsp.gov.gh/api/locations?type=EA&parent_code=0101"
                                    \
                                    -H "Content-Type: application/json"
                                

Sample Response

Success Response - Regions (200 OK)

                                        {
                                        "type": "R",
                                        "quantity": 16,
                                        "data": [
                                        {
                                        "code": "01",
                                        "name": "Greater Accra",
                                        "capital": "Accra",
                                        "leapId": "LEAP-REG-01"
                                        },
                                        {
                                        "code": "02",
                                        "name": "Ashanti",
                                        "capital": "Kumasi",
                                        "leapId": "LEAP-REG-02"
                                        }
                                        ]
                                        }
                                    

Success Response - Districts (200 OK)

                                        {
                                        "type": "D",
                                        "quantity": 29,
                                        "data": [
                                        {
                                        "code": "0101",
                                        "name": "Accra Metropolitan",
                                        "parent_code": "01",
                                        "leapId": "LEAP-DIST-0101"
                                        }
                                        ]
                                        }
                                    

Success Response - Communities (200 OK)

                                        {
                                        "type": "C",
                                        "quantity": 150,
                                        "data": [
                                        {
                                        "code": "010101",
                                        "name": "Jamestown",
                                        "parent_code": "0101",
                                        "leapId": "LEAP-COMM-010101",
                                        "gpsCoordinate": "5.5500,-0.2000",
                                        "focalPersonName": "John Doe",
                                        "focalPersonMobileNumber": "0244123456",
                                        "photoURL": "https://example.com/photo.jpg",
                                        "comments": "Community notes",
                                        "status": "APPROVED",
                                        "error_message": null,
                                        "landmark_info": "Near the lighthouse"
                                        }
                                        ]
                                        }
                                    

Error Response (400 Bad Request)

                                        {
                                        "Error": "Missing required field"
                                        }
                                    

SP MEMIS Statistics (HR13.1)

GET /api/v2/sp_memis

Description

Returns aggregated registry member counts by region and district, with age band and sex breakdown (indicator HR13.1). Requires the same Bearer token validation as other partner APIs: the token must be valid for the supplied partnerCode.

Parameters

Parameter	Type	Required	Default	Description	Example
`partnerCode`	string	Required	-	Partner code; must match the credentials carried in the `Authorization` Bearer token	LEAP

Headers

Header	Required	Description
`Authorization`	Required	Bearer token (GNHR-issued); validated for `partnerCode`

cURL Example

                                    curl -X GET
                                    "https://registry.mogcsp.gov.gh/api/v2/sp_memis?partnerCode=SP_MEMIS" \
                                    -H "Content-Type: application/json" \
                                    -H "Authorization: Bearer <your_token>"
                                

Sample Response

Success Response (200 OK)

                                        {
                                        "data": {
                                        "indicator": "HR13.1",
                                        "regions": [
                                        {
                                        "name": "GREATER ACCRA",
                                        "code": "01",
                                        "districts": [
                                        {
                                        "name": "Accra Metropolitan",
                                        "code": "0101",
                                        "estimated_households": 15000,
                                        "age_range": [
                                        { "age": "0-14", "male": 1200, "female": 1150 },
                                        { "age": "15-24", "male": 800, "female": 820 },
                                        { "age": "25-45", "male": 2100, "female": 2300 },
                                        { "age": "46-60", "male": 600, "female": 650 },
                                        { "age": "60-70", "male": 200, "female": 220 },
                                        { "age": "> 70", "male": 90, "female": 110 }
                                        ]
                                        }
                                        ]
                                        }
                                        ]
                                        }
                                        }
                                    

Error Response (400 Bad Request)

                                        {
                                        "Error": "Missing required field"
                                        }
                                    

Error Response (401 Unauthorized)

                                        {
                                        "error": {
                                        "code": 1001,
                                        "message": "Access denied. Please check your authId, authSecret and ensure your IP address is whitelisted"
                                        }
                                        }
                                    

API Endpoints Summary

Endpoint	Method	Required Parameters	Primary Use Case
`/api/v2/households`	GET	partnerCode + `Authorization: Bearer`	Retrieve households with members data
`/api/v2/households`	PUT	partnerCode + Bearer; JSON body (`action`, UUIDs, `data.purpose`)	Create registry case (legacy path; same body as POST cases)
`/api/registry-cases`	POST	partnerCode + Bearer; JSON body (`action`, UUIDs, `data.purpose`; `communityCode` for `LOCATION_CASE`)	Create registry case with `community_code` support
`/api/registry-cases`	GET	Session `token` header (GNHR admin UI)	List cases; filter by `action`/`type` or `search`
`/api/registry-cases`	PUT	Session `token` + `id`; body `status` and/or `assigned_to`	Update case status or assignment (admin)
`/api/v2/members`	GET	partnerCode + `Authorization: Bearer`	Retrieve individual member records
`/api/locations` `/api/v2/locations`	GET	type	Retrieve location hierarchy data
`/api/v2/sp_memis`	GET	partnerCode + Bearer token	HR13.1 age/sex statistics by region and district (SP MEMIS)

Important Notes

HTTPS Required: All endpoints should be accessed via HTTPS. HTTP requests will be redirected to HTTPS.
Authentication: Some endpoints may require authentication. Check with your system administrator for API keys or tokens.
Rate Limiting: Be mindful of rate limits when making multiple requests. Implement appropriate delays between requests.
Pagination: Use offset and limit parameters to paginate through large result sets.
Data Sharing: The partnerCode parameter determines which data fields are shared based on partner agreements (PMT configuration).
Legacy Data: Use fromLegacy=yes to access data from consolidated legacy tables when needed.
Error Handling: Always check the HTTP status code. 200 indicates success for GET requests; 201 indicates a case was created (POST /api/registry-cases or PUT /api/v2/households). 400 indicates a bad request, 401 unauthorized, 422 database error, and 404 indicates not found.
Response Format: All successful responses return JSON format with a consistent structure.